Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: update wiki/textlint/what-is-textlint.md #1059

Merged
merged 4 commits into from
Sep 28, 2024
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 2 additions & 1 deletion .github/PULL_REQUEST_TEMPLATE.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,8 @@ If your PR references an existing issue, please add the issue number below

- [ ] 번역 초안 작성 (Draft translation)
- [ ] [공통 스타일 가이드 확인 (Check the common style guide)](https://github.com/reactjs/ko.react.dev/blob/main/wiki/universal-style-guide.md)
- [ ] [모범사례 확인 (Check best practices)](https://github.com/reactjs/ko.react.dev/blob/main/wiki/best-practices-for-translation.md)
- [ ] [모범 사례 확인 (Check best practices)](https://github.com/reactjs/ko.react.dev/blob/main/wiki/best-practices-for-translation.md)
- [ ] [용어 확인 (Check the term)](https://github.com/reactjs/ko.react.dev/blob/main/wiki/translate-glossary.md)
- [ ] [Textlint 가이드 확인 (Check the textlint guide)](https://github.com/reactjs/ko.react.dev/blob/main/wiki/textlint/what-is-textlint.md)
- [ ] [맞춤법 검사 (Spelling check)](https://nara-speller.co.kr/speller/)
- [ ] 리뷰 반영 (Resolve reviews)
9 changes: 5 additions & 4 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,10 +8,11 @@

번역을 진행할 때에 다음의 가이드를 따라주세요.

1. 다음과 같은 [공통 스타일 가이드 확인 (Check the common style guide)](/wiki/universal-style-guide.md) 을 따르고 있습니다.
2. [모범사례 확인 (Check best practices)](/wiki/best-practices-for-translation.md) 을 확인해주세요.
3. 공통된 단어 번역을 위해 [용어 확인 (Check the term)](/wiki/translate-glossary.md) 을 참고해주세요.
4. 마지막으로 [맞춤법 검사 (Spelling check)](https://nara-speller.co.kr/speller/) 를 진행해주세요.
1. 다음과 같은 [공통 스타일 가이드 확인 (Check the common style guide)](/wiki/universal-style-guide.md)을 따르고 있습니다.
2. [모범 사례 확인 (Check best practices)](/wiki/best-practices-for-translation.md)을 따라주세요.
3. 공통된 단어 번역을 위해 [용어 확인 (Check the term)](/wiki/translate-glossary.md)을 참고해주세요.
4. 끌어오기(Pull Request) 요청 시 테스트를 통과하지 못할 경우 [Textlint 가이드 확인 (Check the textlint guide)](https://github.com/reactjs/ko.react.dev/blob/main/wiki/textlint/what-is-textlint.md)을 참고해주세요.
5. 마지막으로 [맞춤법 검사 (Spelling check)](https://nara-speller.co.kr/speller/)를 진행해주세요.

이 저장소는 [ko.react.dev](https://ko.react.dev/)의 소스 코드와 개발 문서를 포함하고 있습니다.

Expand Down
2 changes: 2 additions & 0 deletions textlint/data/rules/translateGlossary.js
Original file line number Diff line number Diff line change
@@ -1,3 +1,5 @@
// `sources`에 속한 단어들은 특수한 경우를 제외하고는 기본적으로 '원자성'을 유지해야 합니다. ex) 'stateless component'(x) -> 'stateless'(O), 'component'(O)
// 단, `-`(dash)로 이어진 단어 ex) 'full-stack'은 한개의 단어로 취급합니다.
module.exports = {
translated: {
react: [
Expand Down
152 changes: 138 additions & 14 deletions wiki/textlint/what-is-textlint.md
Original file line number Diff line number Diff line change
@@ -1,16 +1,105 @@
# textlint for ko.reactjs.org
# `textlint` for ko.react.dev

React 공식 페이지 한국어 번역 시 활용하는 [textlint](https://textlint.github.io/)에 대해 설명합니다.
React 공식 페이지 한국어 번역 시 활용하는 [`textlint`](https://textlint.github.io/)에 대해 설명합니다.

## 무엇인가요?

![textlint lint result](https://user-images.githubusercontent.com/7760903/53157203-58da9580-3604-11e9-88dc-59b96b01fe66.png)
```bash
translateGlossary: '인터랙션'은/는 '상호작용'(으)로 번역되어야 합니다.
ko.react.dev/src/content/blog/2022/06/15/react-labs-what-we-have-been-working-on-june-2022.md:74:22
v
73.
74. 이러한 문제를 해결하는 새로운 버전의 인터랙션 추적 API(`startTransition`을 통해 시작되므로 가칭 트랜지션 추적이라고 함)를 개발 중입니다.
75.
^

translateGlossary: '튜토리얼'은/는 '자습서'(으)로 번역되어야 합니다.
ko.react.dev/src/content/blog/2023/03/16/introducing-react-dev.md:60:35
v
59.
60. 직접 해보며 배우고 싶다면, 다음으로 [Tic-Tac-Toe 튜토리얼](/learn/tutorial-tic-tac-toe)을 확인하는 것을 추천합니다. React로 작은 게임을 구현하는 것을 자
세히 설명하면서, 동시에 일상적으로 사용할 기술을 가르칩니다. 여기에 구현하게 될 내용이 있습니다.
61.
^
```

`textlint`는 텍스트(`.txt`)와 마크다운(`.md`, `.mdx`)을 위한 Linter이며 JavaScript로 구현되어 있습니다. [ESLint](https://eslint.org/)가 JavaScript에 가지는 역할과 같습니다.

## 어떻게 실행할 수 있나요?

[`package.json`](/package.json)상에 `scripts`로 등록해 두었기에, 아래와 같은 커맨드로 실행할 수 있습니다.

### 1. 규칙 검사

가장 많이 활용되는 커맨드입니다.

```bash
yarn textlint-lint
```

### 2. 테스트 실행

```bash
yarn textlint-test
```

### 3. 규칙에 따른 문서 생성

```bash
yarn textlint-docs
```

## 어떤 영역을 검사하나요?

`textlint`는 공식 문서에 실질적으로 나타나는 부분인 [`/src/content`](/src/content/) 폴더 내부의 마크다운(`.md`) 파일만을 검사합니다.

### 마크다운 문서 내부에서 검사하지 않는 영역

> [!NOTE]
>
> - `textlint`는 마크다운 문서를 AST Tree로 파싱(Parsing) 합니다. ko.react.dev에서 구현한 규칙은 `@textlint/text-to-ast-14.0.5` 패키지에 의해 AST Tree로 파싱 된 노드(Node)들 중 `Str` 노드만을 검사합니다. ([`/textlint/rules/translateGlossary.js` 참고](/textlint/rules/translateGlossary.js))
>
> - 또한, 모든 `Str` 노드를 검사하는 것은 아닙니다. 영어 원문 번역본이 계속해서 추가되기에, 오직 영어만으로 구성된 `Str` 노드는 검사에서 제외합니다. 즉, 파싱된 `Str` 노드 중 한글이 하나라도 포함된 문장만을 검사합니다. ([`/textlint/utils/is.js` 참고](/textlint/utils/is.js))
>
> - 이외에도, ko.react.dev에서는 `""` 및 `()`로 감싸져 있는 문장은 검사하지 않습니다. `""`에는 주로 에러 메시지 등 영어 원문 그 자체의 내용이 들어가는 경우가 많으며, `()` 역시 독자의 이해를 위해 영어 원문이 그대로 들어가는 경우가 많기 때문입니다. ([`/textlint/utils/strip.js` 참고](/textlint/utils/strip.js))

#### 1. 코드 블럭

````md
```javascript
const hello = 'world';
```
````

#### 2. 인라인 코드 블럭

```md
`hello world`
```

textlint는 텍스트와 마크다운을 위한 linter이며 JavaScript로 구현되어 있습니다. [ESLint](https://eslint.org/)가 JavaScript에 가지는 역할과 같습니다.
#### 3. 한글이 포함되지 않은 문장

```md
This text will not be linted.
```

#### 4. 쌍따옴표(`""`)로 감싸져 있는 문장

```md
"이 문장은 검사되지 않습니다."
```

#### 5. 소괄호(`()`)로 감싸져 있는 문장

```md
(이 문장은 검사되지 않습니다.)
```

## 특정 문맥에서 비활성화할 수 있나요?

[Filter Rule](https://textlint.github.io/docs/configuring.html#filter-rule) 중 하나인 [textlint-filter-rule-comments](https://github.com/textlint/textlint-filter-rule-comments)를 사용해서 비활성화할 수 있습니다. 미리 추가해놨으니 아래처럼 사용하시면 됩니다.
영어 표현을 부득이 하게 사용해야 할 경우, 위에서 언급한 쌍따옴표(`""`)및 소괄호(`()`)를 활용하여 특정 문장을 감쌀 것을 권장합니다.

위 방법을 사용할 수 없는 경우, `textlint`에서 제공하는 [Filter Rule](https://textlint.github.io/docs/configuring.html#filter-rule) 중 하나인 [`textlint-filter-rule-comments`](https://github.com/textlint/textlint-filter-rule-comments)를 사용해서 비활성화할 수 있습니다. 이미 추가되어 있으니 아래처럼 사용하시면 됩니다.

```md
<!-- textlint-disable -->
Expand All @@ -20,25 +109,60 @@ textlint는 텍스트와 마크다운을 위한 linter이며 JavaScript로 구
<!-- textlint-enable -->
```

예를 들어, 한글 문장 안에 의도적으로 번역하지 않은 영어 원문을 사용해야 하는 경우 사용을 고려해 볼 수 있습니다. 이는 `textlint`가 검사하는 일부 영역에 대해 의도적으로 **규칙을 해제(예외를 설정)** 하는 것입니다.

## 새로운 규칙(rule)을 어떻게 만드나요?

[textlint의 공식 문서 Creating Rules](https://textlint.github.io/docs/rule.html)를 숙지하고 다음 과정을 진행해주세요. 모든 코드는 `textlint` 폴더에서 작성됩니다.
[`textlint`의 공식 문서 Creating Rules](https://textlint.github.io/docs/rule.html)를 숙지하고 다음 과정을 진행해주세요.

### ko.react.dev에서만 사용하는 규칙인 경우

`textlint`와 관련된 모든 코드는 [`/textlint`](/textlint) 폴더에 작성합니다.

#### 1. [`/textlint/rules`](/textlint/rules) 폴더에 1개 규칙에 1개 파일 생성

특정 규칙은 `textlint` 커맨드 라인의 `--rulesdir` 옵션을 통해 실행되므로, `/textlint/rules` 폴더 하위에는 규칙과 파일을 대응시켜 작성해주세요.

#### 2. [`/textlint/tests/rules`](/textlint/tests/rules) 폴더에 테스트 코드 작성

- **`rules` 폴더에 1개의 규칙에 1개의 파일 생성**
[`textlint-tester`](https://github.com/textlint/textlint/tree/master/packages/textlint-tester)를 활용해서 작성한 규칙에 대응되는 테스트를 작성해주세요. 올바른 사례와 올바르지 못한 사용 사례를 포함하고, 올바르지 못한 사례는 번역자가 빠르게 수정할 수 있도록 `index`를 통해 오류가 발생한 위치를 알맞게 안내하고 있는지 검증해주세요.

커맨드 라인의 `--rulesdir` 옵션을 통해 실행되므로 `rules` 폴더 하위에는 규칙과 파일을 대응시켜서 작성해주세요.
아래처럼 실행하면 모든 규칙 구현에 대한 테스트를 실행할 수 있습니다.

- **`tests` 폴더에 테스트 코드 작성**
```bash
yarn textlint-test
```

### 외부 규칙을 사용하는 경우

[`textlint-tester`](https://github.com/textlint/textlint/tree/master/packages/textlint-tester)를 활용해서 작성한 규칙에 대응되는 테스트를 작성해주세요. 올바른 사례와 올바르지 못한 사용 사례를 포함하고 올바르지 못한 사례는 번역자가 빠르게 수정할 수 있도록 `index`를 통해 오류가 발생한 위치를 알맞게 안내하고 있는지 검증해주세요.
아래와 같은 예시를 따라주세요.

아래처럼 실행한다면 모든 규칙 구현에 대한 테스트를 실행할 수 있습니다.
#### 1. `yarn`을 통해 특정 패키지를 개발 의존성으로 설치

```bash
yarn add --dev textlint-rule-allowed-uris
```
yarn test:textlint

#### 2. [`/.textlintrc`](/.textlintrc) 파일을 해당 규칙에 맞게 수정

```javascript
module.exports = {
rules: {
'allowed-uris': {
allowed: {
links: [/google/],
},
},
},
};
```

## 주의해야 할 사항이 있나요?

- 모든 글이 번역된 상태가 아니며 번역이 완료되어도 새로운 글은 계속해서 번역이 되어야 하기 때문에 git pre-commit hook에서만 textlint를 실행하며 전체 마크다운 파일을 대상으로 CI에서 실행할 계획은 없습니다. 규칙의 구현에 대한 테스트는 CI에서 실행됩니다.
- `--fix`를 통해 자동으로 수정할 수 있는 [Fixable Rule](https://textlint.github.io/docs/rule-fixable.html)은 의도적으로 작성하지 않습니다. 사람이 코드로 작성한 규칙이기 때문에 완벽하지 않으며 번역자가 인지하지 못한 채로 수정되기보다 문맥을 확인하고 수정하는 방향이 바람직하다고 생각하기 때문입니다.
- `--fix` 옵션을 통해 자동으로 수정할 수 있는 [Fixable Rule](https://textlint.github.io/docs/rule-fixable.html)은 의도적으로 작성하지 않았습니다. 사람이 코드로 작성한 규칙이기 때문에 완벽하지 않으며 번역자가 인지하지 못한 채로 수정되기보다 문맥을 확인하고 수정하는 방향이 바람직하다고 생각하기 때문입니다.

- `textlint`의 검사 기능은 의도적으로 최대한 느슨하게 만들었습니다. 엄격하게 검사를 진행할 경우, 번역 간 문장 이해 및 흐름에 방해가 될 수 있기 때문입니다.

- `.json` 파일 형식으로 구현된 사이드바 메뉴 상의 내용들은 검사하지 않습니다. 따라서, 사이드바 메뉴 상에 표현된 내용들은 직접 수정해야 합니다. `src/sidebarBlog.json` 등이 이에 해당합니다.

- React 문서상의 링크를 연결하기 위해 구현한 `{/* ... */}` 내부의 문자열은 항상 영어로만 구성되므로, [마크다운 문서 내부에서 검사하지 않는 영역](#마크다운-문서-내부에서-검사하지-않는-영역)의 설정에 의해 검사가 자동으로 제외됩니다.
Loading