Skip to content

용어집 ​

용어집은 번역 전반에 걸쳐 일관된 제품 용어를 보장합니다. 사용자는 하나 이상의 언어로 용어의 번역을 정의할 수 있으며, 이를 통해 AI 모델은 자체적으로 번역을 선택하는 대신 미리 정의된 이 번역을 사용하게 됩니다. 또한 제품 이름과 같은 특정 용어가 다른 언어로 번역되는 동안 변경되지 않도록 유지하는 데 사용될 수도 있습니다.

모델에는 두 가지 유형의 가이드가 전송됩니다.

  • glossary.userGlossary의 용어 행(문서, JSON, SVG의 경우 uiGlossary이(가) 활성화된 각 ui 블록의 기존 UI 번역 포함). 행은 해당 소스 용어가 번역 대상 텍스트에 나타나는 경우에만 포함됩니다.
  • glossary.contextFiles의 프로젝트 컨텍스트 파일. 전체 브리프는 모든 UI, 문서, JSON, SVG 및 교정 프롬프트에 주입됩니다. 해당 섹션은 아래에 있습니다.

용어집 작동 방식 ​

용어 출처 ​

소스구성사용 대상
UI 카탈로그ui[].uiGlossary(부울, 기본값 true) — 해당 블록의 stringsJsontranslate-docs, translate-json, translate-svg
사용자 CSVglossary.userGlossarytranslate-ui, proofread-ui, translate-docs, translate-json, translate-svg

init는 glossary.userGlossary이 glossary-user.csv를 가리키도록 하며 해당 파일을 생성하지 않습니다. glossary-generate이(가) 없을 때 실행하고, 첫 번째 translate-ui 앞에 도메인 용어를 넣으세요. 변경되지 않은 문자열의 두 번째 번역은 다르게 표현될 수 있습니다. 용어집이 두 번의 실행을 일치시킵니다.

uiGlossary: true이(가) 포함된 블록은 strings.json에 이미 저장된 번역을 힌트로 재사용하므로 문서, JSON 및 SVG가 UI와 일관성을 유지합니다. translate-ui 및 proofread-ui은(는) 해당 카탈로그를 읽지 않고 사용자 CSV에서만 힌트를 가져오므로, 잘못된 UI 번역이 선호 용어로 다시 반영되지 않습니다. 다른 파이프라인에 영향을 주지 않아야 하는 블록에서는 uiGlossary을(를) false(으)로 설정합니다. 여러 블록이 소스 용어를 공유하는 경우, 앞선 블록이 로케일을 채우고 뒤이어 오는 블록은 아직 누락된 로케일만 추가합니다. 사용자 CSV가 모든 UI 카탈로그보다 우선합니다. locale이(가) 특정 코드인 행은 해당 로케일에 대한 * 행과 UI 카탈로그 번역을 모두 대체합니다. locale이(가) *인 경우 UI 카탈로그의 번역이 아직 없는 모든 대상 로케일에 동일한 번역을 적용합니다.

간결한 UI 레이블 약어(Alm.과(와) 같은 후행 점 또는 Size → Tam과(와) 같은 짧은 단일 토큰 압축)는 UI 번역에 계속 사용할 수 있습니다. 문서 프롬프트는 이를 건너뛰므로, 모델이 마크다운이나 MDX에서 {{…}} 토큰을 임의로 생성하도록 유도하지 않습니다.

둘 이상의 카탈로그 키가 공유하는 여러 단어로 구성된 접두사는 해당 접두사가 아직 키가 아닌 경우 자체 용어로 추가됩니다. 각 로케일에서 번역은 해당 카탈로그 번역의 공유 시작 부분이며, 단어 경계에서 잘라내고, 해당 공유 시작 부분이 최소 4자 이상인 경우에만 해당됩니다. Cursor Models run out 및 Cursor Models at renewal은(는) 두 독일어 문자열이 Cursor-Modelle(으)로 시작할 때 Cursor Models을(를) 생성할 수 있습니다. 동일한 소스에 대한 사용자 CSV 행은 해당 시드 번역을 대체합니다.

용어가 전송되는 시점 ​

일치는 대소문자를 구분하지 않으며 단어 경계(공백 또는 문장 부호)에서 중지됩니다. 더 긴 용어가 우선하며, 겹치는 일치는 삭제됩니다. 용어가 현재 배치와 일치하면 프롬프트는 "dashboard" → "Tableau"과(와) 같은 힌트를 받습니다. 해당 행에 컨텍스트 참고 사항이 있는 경우, 해당 참고 사항은 해당 일치 항목에만 추가됩니다.

컨텍스트는 소스 언어 사용 지침(용어의 의미 또는 사용 방법)입니다. 번역이 아닙니다. 컨텍스트 메모 또는 glossary.contextFiles 콘텐츠를 변경하면 다음 실행 시 영향을 받는 로케일의 캐시된 번역이 새로 고쳐집니다. --force이(가) 필요하지 않습니다. 강제가 아닌 행에서 기본 설정 번역만 변경하면 --force 또는 --force-update을(를) 전달할 때까지 기존 캐시가 유지됩니다. 강제 행(신규, 편집 또는 삭제)은 해당 용어가 포함된 소스의 세그먼트에 대해서만, 그리고 저장된 텍스트에 강제 번역이 아직 포함되지 않은 경우에만 캐시를 누락합니다. 이 좁은 새로 고침을 위해 해당 행에서 컨텍스트를 비워 둡니다. 컨텍스트 메모는 여전히 전체 로케일을 새로 고칩니다. 대시보드에서 편집한 행은 user-edited(으)로 유지됩니다.

마크다운 번역은 소스가 전체 볼드체 또는 인라인 코드 스팬, 헤더 또는 해당 레이블만 있는 줄로 인용할 때 2~5단어 길이의 UI 레이블을 확인합니다. 용어를 포함하는 더 긴 볼드체 구문은 힌트이므로, **Ask for target language**은(는) Target language의 카탈로그 형식을 요구하지 않습니다. 단일 단어 힌트는 여전히 굴절될 수 있습니다. UI 레이블이 아닌 사용자 CSV 힌트는 힌트로 유지됩니다. 확인 시 대소문자를 무시하고 카탈로그 문구를 부분 문자열로 찾으므로, 굴절된 형태도 누락될 수 있습니다. 동일한 품질 오류가 세 번 발생하거나 모델 목록이 소진될 때까지 다음 모델을 시도하며, 레이블 누락으로 인해 세그먼트를 분할하지 않습니다. 해당 시도들이 해당 확인만 놓치는 경우, 실행은 가장 적은 누락이 있는 시도를 유지하고, 문서를 작성하며, 용어집 레이블 경고와 함께 세그먼트를 캐시합니다. 요약은 해당 경고들을 나열하며, cacheDir는 각 누락을 오탐(false positive) 또는 실제 누락(real miss)으로 표시하도록 AI에 붙여넣을 수 있는 프롬프트인 glossary-review-*.md을(를) 받습니다. 유일한 문제가 해당 경고일 때 종료 코드는 0으로 유지됩니다.

오탐은 프로젝트 구성의 glossary.labelCheckSkips을(를) 사용하여 건너뛸 수 있습니다 (대시보드 용어집 탭에서 동일한 목록을 편집합니다). 각 항목은 영어 term, 건너뛸 locales (*는 모든 로케일을 의미함), 그리고 선택적 files 글로브를 지정합니다. 해당 용어는 프롬프트 힌트로 유지됩니다. --recheck-glossary-warnings는 플래그가 지정된 세그먼트를 다시 번역하고, 이제 검사가 통과되면 플래그를 지웁니다. --force는 다른 모든 세그먼트와 함께 이를 다시 번역합니다. 캐시된 마크다운은 파일이 처리될 때 (--force-update) 다시 확인됩니다. 파일 추적이 건너뛰는 파일은 해당 파일의 Force 용어가 출력에서 누락되거나 --recheck-glossary-warnings이 플래그가 지정된 세그먼트가 있는 파일을 열 때까지 그대로 유지됩니다. 해당 레이블이 인용되는 모든 곳에서, 번역된 제품 이름을 포함하여, 원본과 다른 카탈로그 번역이 필요합니다. 번역이 원본과 동일한 Force 행을 사용하여 원본 철자를 유지합니다.

강제 적용 ​

강제 적용이(가) true, yes 또는 1인 경우, 모델이 텍스트를 보기 전에 소스 용어가 텍스트에서 제거되고 나중에 기본 번역이 다시 기록됩니다. 이 문구는 제안이 아닌 정확한 표현입니다. 동일한 단어 경계 및 최장 일치 규칙이 적용됩니다. 모델이 번역을 선호하지만 여전히 굴절시킬 수 있는 경우에는 강제 적용을(를) 비워두거나 false(으)로 두세요.

용어집 생성 ​

glossary-generate은(는) 표준 헤더가 있는 빈 CSV를 작성합니다. 구성의 glossary.userGlossary을(를) 사용하거나, 해당 키가 설정되지 않은 경우 glossary-user.csv을(를) 사용합니다. 이미 존재하는 파일을 덮어쓰지 않습니다(종료 1).

bash
ai-i18n-tools glossary-generate
# or: ai-i18n-tools glossary-generate -o i18n/glossary.csv

구성에서 파일을 지정합니다.

json
{
  "glossary": {
    "userGlossary": "i18n/glossary.csv"
  }
}

대시보드에서 직접 CSV 용어집 파일을 생성할 수도 있습니다. 용어집 탭에서 처음 추가 작업을 수행할 때 glossary.userGlossary이(가) 지정되어 있고 파일이 아직 존재하지 않으면 파일이 생성됩니다. glossary.autoAddUserEditedToGlossary이(가) true(기본값)로 설정된 경우 대시보드에서 UI 문자열을 수정하면 다음 translate-ui 실행 시 해당 변경 내용이 CSV에 추가됩니다. 또한 대시보드는 CSV 용어집 편집기 역할을 하여 UI 내에서 행을 추가, 편집 또는 필터링할 수 있습니다.

CSV 열 ​

헤더 행:

text
Original language string,locale,Translation,Force,Context

Original language string 대신 en 또는 English이(가) 허용됩니다. Context 대신 Notes이(가) 허용됩니다.

열의미
원본 언어 문자열소스 로케일의 소스 용어 또는 구문
로케일대상 로케일 코드, 또는 모든 대상에 대한 *
번역선호하는 번역
강제이 문구를 강제하려면 true, yes 또는 1를 지정하고, 그렇지 않으면 힌트로 사용
컨텍스트선택 사항인 소스 언어 설명. 이 용어가 일치할 때만 전송됨

예시 ​

모든 로케일에 대한 제품 용어 하나, 강제된 독일어 레이블, 그리고 모델이 문자 그대로 받아들일 수 있는 단어를 설명하는 프랑스어 행:

csv
"Original language string","locale","Translation","Force","Context"
"dashboard","*","Tableau","false","The analytics home, not a vehicle panel"
"Save","de","Speichern","true",""
"workspace","fr","espace de travail","false","A user's project container, not an office"

프로젝트 요약과 결합 시:

json
{
  "glossary": {
    "userGlossary": "i18n/glossary.csv",
    "contextFiles": ["i18n/product-context.md"],
    "contextMaxChars": 12000
  }
}

필드 참조: 구성의 glossary. 명령 참조: glossary-generate.

프로젝트 컨텍스트 파일 ​

glossary.contextFiles는 단일 CSV 행에 속하지 않는 제품 수준의 가이드를 위한 것입니다: 제품이 무엇인지, 누구를 위한 것인지, 어조, 그리고 오역하기 쉬운 용어입니다. config를 하나 이상의 cwd 상대 경로의 .md / .txt 파일로 지정하면, 나열된 순서대로 연결되어 모든 UI, 문서, JSON, SVG 및 교정 프롬프트에 주입됩니다.

json
{
  "glossary": {
    "userGlossary": "i18n/glossary.csv",
    "contextFiles": ["i18n/product-context.md"]
  }
}

브리프를 소스 로케일로 작성하고, glossary.contextMaxChars(기본값 12000)를 크게 밑도록 유지하며, 해당 파일도 번역하려는 경우가 아니라면 docs[].contentPaths 외부에 저장하십시오. 구성의 glossary를 참조하십시오.

AI 에이전트로 컨텍스트 파일 생성 ​

에이전트(Cursor, Claude Code, Copilot 등)에게 리포지토리를 읽고 브리프를 작성하도록 요청하십시오. 다음과 같은 프롬프트를 붙여넣으십시오:

text
Create a translation-context Markdown file for this repository at i18n/product-context.md.

This file is injected verbatim into every ai-i18n-tools translation prompt (UI strings, docs, JSON, SVG, proofread). It must stay in the source language of the project (do not translate it). Translators already receive a glossary of preferred term mappings; this file should explain meaning, audience, and register — not duplicate every glossary row.

Requirements:
- Concise: aim for 1–4 KB, hard limit 8000 characters. No full manuals, README dumps, or changelog history.
- Source-language only. Short headings, bullet lists, and a few example sentences are enough.
- No secrets, API keys, credentials, personal data, internal URLs, or unpublished commercial figures.
- Do not invent product facts. If something is unclear, omit it or mark it as unknown.
- Do not put this file under a path that is also listed in docs[].contentPaths.

Cover, in this order:
1. Product in one paragraph: what it is, who uses it, and the default tone (formal / informal / technical).
2. Domain and disambiguation: terms that look ordinary in English but have a product-specific meaning (for example “dashboard” as an analytics home, not a vehicle panel).
3. Features or areas that change register (billing vs. onboarding vs. admin).
4. Things translators must preserve exactly: brand names, CLI flags, config keys, code identifiers, placeholder tokens.
5. Locale notes only when they affect meaning for every target (for example “use formal you”). Do not list per-locale translations here.

Write only the Markdown file. Afterward, remind me to add it to glossary.contextFiles in ai-i18n-tools.config.json if it is not already listed.

다음 sync / translate-* 실행 전에 파일을 검토하십시오. 파일을 변경하면 해당 실행에서 각 로케일의 캐시된 번역이 무효화되므로, 품질이 양호해지면 브리프를 안정적으로 유지하십시오.

MIT 라이선스에 따라 배포됩니다.