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

* docs: update wiki/textlint/what-is-textlint.md

* docs: update README.md

* docs: update PULL_REQUEST_TEMPLATE.md

* refactor: add comments in translateGlossary.js

.github/PULL_REQUEST_TEMPLATE.md

@@ -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)

README.md

@@ -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/)의 소스 코드와 개발 문서를 포함하고 있습니다.
 

textlint/data/rules/translateGlossary.js

@@ -1,3 +1,5 @@
+// `sources`에 속한 단어들은 특수한 경우를 제외하고는 기본적으로 '원자성'을 유지해야 합니다. ex) 'stateless component'(x) -> 'stateless'(O), 'component'(O)
+// 단, `-`(dash)로 이어진 단어 ex) 'full-stack'은 한개의 단어로 취급합니다.
 module.exports = {
   translated: {
     react: [

wiki/textlint/what-is-textlint.md

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