You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: README.md
+5-4
Original file line number
Diff line number
Diff line change
@@ -8,10 +8,11 @@
8
8
9
9
번역을 진행할 때에 다음의 가이드를 따라주세요.
10
10
11
-
1. 다음과 같은 [공통 스타일 가이드 확인 (Check the common style guide)](/wiki/universal-style-guide.md) 을 따르고 있습니다.
12
-
2.[모범사례 확인 (Check best practices)](/wiki/best-practices-for-translation.md) 을 확인해주세요.
13
-
3. 공통된 단어 번역을 위해 [용어 확인 (Check the term)](/wiki/translate-glossary.md) 을 참고해주세요.
14
-
4. 마지막으로 [맞춤법 검사 (Spelling check)](https://nara-speller.co.kr/speller/) 를 진행해주세요.
11
+
1. 다음과 같은 [공통 스타일 가이드 확인 (Check the common style guide)](/wiki/universal-style-guide.md)을 따르고 있습니다.
12
+
2.[모범 사례 확인 (Check best practices)](/wiki/best-practices-for-translation.md)을 따라주세요.
13
+
3. 공통된 단어 번역을 위해 [용어 확인 (Check the term)](/wiki/translate-glossary.md)을 참고해주세요.
14
+
4. 끌어오기(Pull Request) 요청 시 테스트를 통과하지 못할 경우 [Textlint 가이드 확인 (Check the textlint guide)](https://github.com/reactjs/ko.react.dev/blob/main/wiki/textlint/what-is-textlint.md)을 참고해주세요.
15
+
5. 마지막으로 [맞춤법 검사 (Spelling check)](https://nara-speller.co.kr/speller/)를 진행해주세요.
15
16
16
17
이 저장소는 [ko.react.dev](https://ko.react.dev/)의 소스 코드와 개발 문서를 포함하고 있습니다.
60. 직접 해보며 배우고 싶다면, 다음으로 [Tic-Tac-Toe 튜토리얼](/learn/tutorial-tic-tac-toe)을 확인하는 것을 추천합니다. React로 작은 게임을 구현하는 것을 자
21
+
세히 설명하면서, 동시에 일상적으로 사용할 기술을 가르칩니다. 여기에 구현하게 될 내용이 있습니다.
22
+
61.
23
+
^
24
+
```
25
+
26
+
`textlint`는 텍스트(`.txt`)와 마크다운(`.md`, `.mdx`)을 위한 Linter이며 JavaScript로 구현되어 있습니다. [ESLint](https://eslint.org/)가 JavaScript에 가지는 역할과 같습니다.
27
+
28
+
## 어떻게 실행할 수 있나요?
29
+
30
+
[`package.json`](/package.json)상에 `scripts`로 등록해 두었기에, 아래와 같은 커맨드로 실행할 수 있습니다.
31
+
32
+
### 1. 규칙 검사
33
+
34
+
가장 많이 활용되는 커맨드입니다.
35
+
36
+
```bash
37
+
yarn textlint-lint
38
+
```
39
+
40
+
### 2. 테스트 실행
41
+
42
+
```bash
43
+
yarn textlint-test
44
+
```
45
+
46
+
### 3. 규칙에 따른 문서 생성
47
+
48
+
```bash
49
+
yarn textlint-docs
50
+
```
51
+
52
+
## 어떤 영역을 검사하나요?
53
+
54
+
`textlint`는 공식 문서에 실질적으로 나타나는 부분인 [`/src/content`](/src/content/) 폴더 내부의 마크다운(`.md`) 파일만을 검사합니다.
55
+
56
+
### 마크다운 문서 내부에서 검사하지 않는 영역
57
+
58
+
> [!NOTE]
59
+
>
60
+
> -`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))
61
+
>
62
+
> - 또한, 모든 `Str` 노드를 검사하는 것은 아닙니다. 영어 원문 번역본이 계속해서 추가되기에, 오직 영어만으로 구성된 `Str` 노드는 검사에서 제외합니다. 즉, 파싱된 `Str` 노드 중 한글이 하나라도 포함된 문장만을 검사합니다. ([`/textlint/utils/is.js` 참고](/textlint/utils/is.js))
63
+
>
64
+
> - 이외에도, ko.react.dev에서는 `""` 및 `()`로 감싸져 있는 문장은 검사하지 않습니다. `""`에는 주로 에러 메시지 등 영어 원문 그 자체의 내용이 들어가는 경우가 많으며, `()` 역시 독자의 이해를 위해 영어 원문이 그대로 들어가는 경우가 많기 때문입니다. ([`/textlint/utils/strip.js` 참고](/textlint/utils/strip.js))
65
+
66
+
#### 1. 코드 블럭
67
+
68
+
````md
69
+
```javascript
70
+
const hello = 'world';
71
+
```
72
+
````
73
+
74
+
#### 2. 인라인 코드 블럭
75
+
76
+
```md
77
+
`hello world`
78
+
```
8
79
9
-
textlint는 텍스트와 마크다운을 위한 linter이며 JavaScript로 구현되어 있습니다. [ESLint](https://eslint.org/)가 JavaScript에 가지는 역할과 같습니다.
80
+
#### 3. 한글이 포함되지 않은 문장
81
+
82
+
```md
83
+
This text will not be linted.
84
+
```
85
+
86
+
#### 4. 쌍따옴표(`""`)로 감싸져 있는 문장
87
+
88
+
```md
89
+
"이 문장은 검사되지 않습니다."
90
+
```
91
+
92
+
#### 5. 소괄호(`()`)로 감싸져 있는 문장
93
+
94
+
```md
95
+
(이 문장은 검사되지 않습니다.)
96
+
```
10
97
11
98
## 특정 문맥에서 비활성화할 수 있나요?
12
99
13
-
[Filter Rule](https://textlint.github.io/docs/configuring.html#filter-rule) 중 하나인 [textlint-filter-rule-comments](https://github.com/textlint/textlint-filter-rule-comments)를 사용해서 비활성화할 수 있습니다. 미리 추가해놨으니 아래처럼 사용하시면 됩니다.
100
+
영어 표현을 부득이 하게 사용해야 할 경우, 위에서 언급한 쌍따옴표(`""`)및 소괄호(`()`)를 활용하여 특정 문장을 감쌀 것을 권장합니다.
101
+
102
+
위 방법을 사용할 수 없는 경우, `textlint`에서 제공하는 [Filter Rule](https://textlint.github.io/docs/configuring.html#filter-rule) 중 하나인 [`textlint-filter-rule-comments`](https://github.com/textlint/textlint-filter-rule-comments)를 사용해서 비활성화할 수 있습니다. 이미 추가되어 있으니 아래처럼 사용하시면 됩니다.
14
103
15
104
```md
16
105
<!-- textlint-disable -->
@@ -20,25 +109,60 @@ textlint는 텍스트와 마크다운을 위한 linter이며 JavaScript로 구
20
109
<!-- textlint-enable -->
21
110
```
22
111
112
+
예를 들어, 한글 문장 안에 의도적으로 번역하지 않은 영어 원문을 사용해야 하는 경우 사용을 고려해 볼 수 있습니다. 이는 `textlint`가 검사하는 일부 영역에 대해 의도적으로 **규칙을 해제(예외를 설정)** 하는 것입니다.
113
+
23
114
## 새로운 규칙(rule)을 어떻게 만드나요?
24
115
25
-
[textlint의 공식 문서 Creating Rules](https://textlint.github.io/docs/rule.html)를 숙지하고 다음 과정을 진행해주세요. 모든 코드는 `textlint` 폴더에서 작성됩니다.
116
+
[`textlint`의 공식 문서 Creating Rules](https://textlint.github.io/docs/rule.html)를 숙지하고 다음 과정을 진행해주세요.
117
+
118
+
### ko.react.dev에서만 사용하는 규칙인 경우
119
+
120
+
`textlint`와 관련된 모든 코드는 [`/textlint`](/textlint) 폴더에 작성합니다.
121
+
122
+
#### 1. [`/textlint/rules`](/textlint/rules) 폴더에 1개 규칙에 1개 파일 생성
123
+
124
+
특정 규칙은 `textlint` 커맨드 라인의 `--rulesdir` 옵션을 통해 실행되므로, `/textlint/rules` 폴더 하위에는 규칙과 파일을 대응시켜 작성해주세요.
125
+
126
+
#### 2. [`/textlint/tests/rules`](/textlint/tests/rules) 폴더에 테스트 코드 작성
26
127
27
-
-**`rules` 폴더에 1개의 규칙에 1개의 파일 생성**
128
+
[`textlint-tester`](https://github.com/textlint/textlint/tree/master/packages/textlint-tester)를 활용해서 작성한 규칙에 대응되는 테스트를 작성해주세요. 올바른 사례와 올바르지 못한 사용 사례를 포함하고, 올바르지 못한 사례는 번역자가 빠르게 수정할 수 있도록 `index`를 통해 오류가 발생한 위치를 알맞게 안내하고 있는지 검증해주세요.
28
129
29
-
커맨드 라인의 `--rulesdir` 옵션을 통해 실행되므로 `rules` 폴더 하위에는 규칙과 파일을 대응시켜서 작성해주세요.
130
+
아래처럼 실행하면 모든 규칙 구현에 대한 테스트를 실행할 수 있습니다.
30
131
31
-
-**`tests` 폴더에 테스트 코드 작성**
132
+
```bash
133
+
yarn textlint-test
134
+
```
135
+
136
+
### 외부 규칙을 사용하는 경우
32
137
33
-
[`textlint-tester`](https://github.com/textlint/textlint/tree/master/packages/textlint-tester)를 활용해서 작성한 규칙에 대응되는 테스트를 작성해주세요. 올바른 사례와 올바르지 못한 사용 사례를 포함하고 올바르지 못한 사례는 번역자가 빠르게 수정할 수 있도록 `index`를 통해 오류가 발생한 위치를 알맞게 안내하고 있는지 검증해주세요.
138
+
아래와 같은 예시를 따라주세요.
34
139
35
-
아래처럼 실행한다면 모든 규칙 구현에 대한 테스트를 실행할 수 있습니다.
140
+
#### 1. `yarn`을 통해 특정 패키지를 개발 의존성으로 설치
36
141
142
+
```bash
143
+
yarn add --dev textlint-rule-allowed-uris
37
144
```
38
-
yarn test:textlint
145
+
146
+
#### 2. [`/.textlintrc`](/.textlintrc) 파일을 해당 규칙에 맞게 수정
147
+
148
+
```javascript
149
+
module.exports= {
150
+
rules: {
151
+
'allowed-uris': {
152
+
allowed: {
153
+
links: [/google/],
154
+
},
155
+
},
156
+
},
157
+
};
39
158
```
40
159
41
160
## 주의해야 할 사항이 있나요?
42
161
43
-
- 모든 글이 번역된 상태가 아니며 번역이 완료되어도 새로운 글은 계속해서 번역이 되어야 하기 때문에 git pre-commit hook에서만 textlint를 실행하며 전체 마크다운 파일을 대상으로 CI에서 실행할 계획은 없습니다. 규칙의 구현에 대한 테스트는 CI에서 실행됩니다.
44
-
-`--fix`를 통해 자동으로 수정할 수 있는 [Fixable Rule](https://textlint.github.io/docs/rule-fixable.html)은 의도적으로 작성하지 않습니다. 사람이 코드로 작성한 규칙이기 때문에 완벽하지 않으며 번역자가 인지하지 못한 채로 수정되기보다 문맥을 확인하고 수정하는 방향이 바람직하다고 생각하기 때문입니다.
162
+
-`--fix` 옵션을 통해 자동으로 수정할 수 있는 [Fixable Rule](https://textlint.github.io/docs/rule-fixable.html)은 의도적으로 작성하지 않았습니다. 사람이 코드로 작성한 규칙이기 때문에 완벽하지 않으며 번역자가 인지하지 못한 채로 수정되기보다 문맥을 확인하고 수정하는 방향이 바람직하다고 생각하기 때문입니다.
163
+
164
+
-`textlint`의 검사 기능은 의도적으로 최대한 느슨하게 만들었습니다. 엄격하게 검사를 진행할 경우, 번역 간 문장 이해 및 흐름에 방해가 될 수 있기 때문입니다.
165
+
166
+
-`.json` 파일 형식으로 구현된 사이드바 메뉴 상의 내용들은 검사하지 않습니다. 따라서, 사이드바 메뉴 상에 표현된 내용들은 직접 수정해야 합니다. `src/sidebarBlog.json` 등이 이에 해당합니다.
167
+
168
+
- React 문서상의 링크를 연결하기 위해 구현한 `{/* ... */}` 내부의 문자열은 항상 영어로만 구성되므로, [마크다운 문서 내부에서 검사하지 않는 영역](#마크다운-문서-내부에서-검사하지-않는-영역)의 설정에 의해 검사가 자동으로 제외됩니다.
0 commit comments