구성 참조
sourceLocale
소스 언어의 BCP-47 코드입니다(예: "en-GB", "pt-BR" 또는 "ja"). 모든 언어가 유효합니다. 많은 프로젝트가 영어로 시작하기 때문에 예시에는 영어가 사용되었습니다. 이 로케일의 경우 번역 파일이 생성되지 않으며, 키 문자열 자체가 소스 텍스트가 됩니다.
일치해야 함 런타임 i18n 설정 파일(src/i18n.ts / src/i18n.js)에서 내보낸 SOURCE_LOCALE과.
targetLocales
번역할 BCP-47 로캘 코드 배열 (예: ["de", "fr", "es", "pt-BR"]).
targetLocales은 UI 번역을 위한 기본 로캘 목록이자 문서 블록의 기본 로캘 목록입니다. sourceLocale + targetLocales에서 ui-languages.json 매니페스트를 생성하려면 generate-ui-languages을 사용하세요.
uiLanguage (선택 사항)
도구 자체 UI 언어(CLI 도움말, 로그/요약, 번역 대시보드)의 BCP-47 코드입니다. sourceLocale / targetLocales과(와) 독립적이며, -L / --ui-lang 플래그 및 AI_I18N_LANG 환경 변수에 의해 재정의됩니다. 알 수 없는 값은 소스 로케일(en-GB)로 정상적으로 저하되며, 엄격한 유효성 검사는 수행되지 않습니다. 도구 UI 언어를 참조하세요.
languagesManifestPath (선택 사항)
루트 수준의 선택적 문자열입니다. 문서 언어 전환기가 이 경로를 읽습니다. 생략하면 첫 번째 UI 블록의 매니페스트, 즉 해당 블록의 languagesManifestPath 또는 {flatOutputDir}/ui-languages.json이(가) 기본값으로 사용됩니다. 각 UI 블록은 자체 languagesManifestPath을(를) 설정할 수 있으며, 블록 0은 자체 값을 생략하면 이 루트 경로를 사용합니다.
다음과 같은 경우에 사용하세요:
- 매니페스트는
ui.flatOutputDir외부에 위치해야 합니다 (예:src/i18n/아래의 앱 헬퍼 옆). - 언어 전환 후처리 (
languageListBlock)가 번들된 마스터 카탈로그만이 아닌 프로젝트 매니페스트로부터 로케일 라벨을 빌드하도록 하려는 경우.
includeUiLanguageEnglishNames는 이 파일을 읽지 않습니다 — 번들된 마스터 카탈로그를 사용합니다 (아래 ui.uiExtractor 참조).
레거시: 구성 파일을 로드할 때 루트 수준의 uiLanguagesPath는 여전히 허용되며, 자동으로 languagesManifestPath로 다시 작성됩니다.
concurrency (선택 사항)
동시에 번역되는 최대 대상 로케일 수 (translate-ui, translate-docs, translate-svg 및 sync 내의 일치하는 단계). 생략하면 CLI는 UI 번역에 4를, 문서 번역에 3를 사용합니다(내장 기본값). 실행 시마다 -j / --concurrency로 재정의할 수 있습니다.
batchConcurrency (선택 사항)
translate-docs, translate-svg, translate-json (및 sync 내부의 일치하는 단계): 파일당 최대 병렬 LLM batch 요청 (각 배치에는 여러 세그먼트가 포함될 수 있음). 생략 시 기본값 4. translate-ui에는 적용되지 않음 — 대신 uiBatchConcurrency를 사용하십시오. -b / --batch-concurrency로 재정의.
uiBatchConcurrency (선택 사항)
translate-ui, sync-ui, 및 sync의 UI 단계: 단일 로케일 내 최대 병렬 LLM batch 요청 (50개의 일반 문자열 청크, 그 다음 복수형 그룹). 생략 시 기본값 2. concurrency (병렬 대상 로케일) 및 batchConcurrency (docs/JSON/SVG)와 독립적임. CLI 플래그 없음; config에서 설정하거나 프로그래밍 방식 runTranslateUI에 uiBatchConcurrency를 전달.
예시:
{
"uiBatchConcurrency": 2
}기본 로케일 동시성 4를 사용하면, 최대 8개의 진행 중인 UI API 호출이 가능합니다. 하나의 큰 로케일을 번역할 때 (-l de) 이 값을 높이고; 제공자가 속도를 제한하는 경우 낮게 유지하십시오.
fileConcurrency (선택 사항)
단일 로케일 내에서 동시에 처리되는 파일의 최대 개수 (하나의 로케일 내). translate-docs 및 sync 중에 사용됩니다. 1보다 큰 값으로 설정된 경우, 동일한 로케일 내 파일들이 메모리 사용량을 제어하기 위한 세마포어를 사용하여 병렬로 처리됩니다. 생략 시 기본값은 1(순차 처리)입니다. 더 높은 값은 I/O에 의해 제한되는 작업의 처리량을 크게 향상시킬 수 있으며, 특히 모든 세그먼트가 이미 캐시되어 있는 경우(별도의 API 호출이 필요 없는 경우) 더욱 효과적입니다.
예시:
{
"fileConcurrency": 4
}사용 사례: 전체 처리 시간을 줄이기 위해 캐시 적중률이 100%인 상태에서 sync --force-update을 실행할 때 이 값을 2-4으로 설정합니다. 이는 작은 파일이 많은 경우에 특히 두드러진 개선을 보입니다.
batchSize / maxBatchChars (선택 사항)
translate-docs, translate-svg 및 translate-json에 대한 세그먼트 배치: API 요청당 세그먼트 수 및 문자 상한. 기본값: 20 세그먼트, 4096 문자(생략 시).
requestTimeout / requestTimeoutMs (선택 사항)
각 LLM 요청에 대해 모든 공급자에 대한 최대 대기 시간입니다. requestTimeout는 전체 초 단위이고, requestTimeoutMs는 밀리초 단위입니다. 둘 다 생략된 경우 기본값은 120초입니다. 둘 중 하나만 설정하십시오. 어떤 필드든 설정하는 공급자는 해당 공급자에 한해 그 값을 대신 사용합니다.
provider 및 providers
provider (최상위, 선택 사항)은 providers에서 활성 공급자 키를 선택합니다. 구성된 공급자가 하나뿐인 경우 선택 사항이며, 둘 이상 구성된 경우 필수입니다.
providers (최상위)는 공급자 키를 해당 블록에 매핑합니다. 내장 키 (아래 사전 설정 테이블 참조)는 translationModels만 필요합니다. 다른 키는 사용자 지정 OpenAI 호환 엔드포인트를 정의하며 baseUrl (및 apiKeyEnv, 엔드포인트에 키가 필요하지 않은 경우 제외)가 필요합니다.
각 providers.<name> 블록은 다음을 허용합니다:
translationModels선호하는 모델 ID의 정렬된 목록(일반적인 업스트림 ID,provider/접두사 없음; OpenRouter ID는 고유한vendor/model형식을 유지합니다). 첫 번째 항목이 먼저 시도되고, 이후 항목은 오류 발생 시 대체 항목으로 사용됩니다. 이는 더 구체적인 계층이 적용되지 않을 때 모든 파이프라인에 대한 전역 기본 체인입니다.uiModels(선택 사항)translate-ui, 복수 생성(단계 0 및 통과 B) 및proofread-ui를 위한 정렬된 UI 전용 모델 목록입니다. 대상 로케일에 대한 일치하는localeModels항목 다음에,translationModels이전에 시도됩니다.localeModels(선택 사항) 모든 번역 파이프라인에 대한 로케일별 재정의입니다.{ "locale": "<BCP-47>", "models": ["…"] }객체의 배열입니다. 로케일 태그는 대소문자를 구분하지 않고 일치합니다(pt-br=pt-BR). 각 로케일의 목록은 해당 로케일에 대해서만 먼저 시도된 다음, 파이프라인별 계층(UI의 경우uiModels) 및translationModels이 시도됩니다. 중복된 정규화된 로케일 키는 구성 로드 시 거부됩니다.baseUrlOpenAI 호환 기본 URL. 사전 설정된 기본 URL을 재정의합니다. 사전 설정되지 않은 공급자에게 필요합니다.apiKeyEnvAPI 키를 포함하는 환경 변수입니다. 사전 설정된 환경 변수를 재정의합니다.headers이 공급자에 대한 모든 요청과 함께 전송되는 추가 HTTP 헤더입니다.maxTokens요청당 최대 완료 토큰 수입니다. 기본값:8192.temperature샘플링 온도입니다. 기본값:0.2.requestTimeout이 공급자에 대한 각 요청에 대해 초 단위로 대기할 최대 시간입니다. 최상위requestTimeout/requestTimeoutMs를 재정의합니다. 이 공급자나 최상위 구성(config)이 시간 초과를 설정하지 않은 경우, 기본값은120초입니다. 동일한 객체에서requestTimeout와requestTimeoutMs중 하나만 설정하십시오.requestTimeoutMs이 공급자에 대한 각 요청에 대해 밀리초 단위로 대기할 최대 시간입니다. 최상위requestTimeout/requestTimeoutMs를 재정의합니다. 이 공급자나 최상위 구성(config)이 시간 초과를 설정하지 않은 경우, 기본값은120000(120초)입니다. 동일한 객체에서requestTimeout과requestTimeoutMs중 하나만 설정하십시오.pricing(선택 사항) 공급자 전체 100만 토큰당 USD:{ "inputPerMTokens": 0.15, "outputPerMTokens": 0.6 }. 청구된 호출에 공급자가 보고한usage.cost가 없는 경우(OpenRouter 및 Cheaper Inference를 제외한 대부분의 공급자), 이 요율이 해당 호출의 입력 및 출력 토큰에 적용됩니다. 이 금액은 번역 요약에 포함되며api_calls행에 저장됩니다.
비용 출처는 다음 순서로 결정됩니다:
- 일치하는
modelPricing항목 (이 공급자 기본값을 재정의합니다); - 공급자가 보고한 비용 (절대 대체되지 않습니다);
- 이
pricing요율; - 해당 모델 ID에 대한 models.dev 정가 (입력 및 출력 100만 토큰당 USD).
비용 없이 저장된 행은 나중에 usage 및 사용량 및 비용을 통해 추정할 수 있습니다. 이러한 출처 중 어느 것도 적용되지 않으면 비용은 알 수 없음(—)으로 유지되며, $0.00가 되지 않습니다.
modelPricing(선택 사항) 모델당 100만 토큰당 USD:{ "<model-id>": { "inputPerMTokens": 2.5, "outputPerMTokens": 10 } }. 해당 모델 ID에 대한pricing를 재정의합니다. 공급자가usage.cost를 생략했을 때 호출 시 적용되며, 호출과 함께 저장됩니다.zeroDataRetention(선택 사항,providers.cheaperinference만 해당)true일 때, 채팅 요청은"zdr": true및list-models,check-models를 보내고,suggest-models은GET /v1/models?zdr=true를 로드합니다. 생략하면 비활성화됩니다. 데이터 보존 없음을 참조하십시오.
내장 제공자 사전 설정(키 — 기본 URL — API 키 환경 변수):
| 공급자 | 기본 URL | API 키 환경 변수 |
|---|---|---|
alibaba | https://dashscope-intl.aliyuncs.com/compatible-mode/v1 | ALIBABA_API_KEY |
anthropic | https://api.anthropic.com/v1 | ANTHROPIC_API_KEY |
apikeyfan | https://api.apikey.fan/v1 | APIKEYFAN_API_KEY |
cerebras | https://api.cerebras.ai/v1 | CEREBRAS_API_KEY |
cheaperinference | https://api.cheaperinference.com/v1 | CHEAPERINFERENCE_API_KEY |
deepseek | https://api.deepseek.com | DEEPSEEK_API_KEY |
gemini | https://generativelanguage.googleapis.com/v1beta/openai | GOOGLE_API_KEY |
groq | https://api.groq.com/openai/v1 | GROQ_API_KEY |
mistral | https://api.mistral.ai/v1 | MISTRAL_API_KEY |
nvidia | https://integrate.api.nvidia.com/v1 | NVIDIA_API_KEY |
ollama | http://localhost:11434/v1 | (없음) |
openai | https://api.openai.com/v1 | OPENAI_API_KEY |
openrouter | https://openrouter.ai/api/v1 | OPENROUTER_API_KEY |
xai | https://api.x.ai/v1 | XAI_API_KEY |
apifun 프리셋의 이름이 apikeyfan(으)로 변경되었습니다. 기존 구성에서 provider 및 providers 키를 업데이트하세요. APIFUN_API_KEY는 APIKEYFAN_API_KEY의 별칭으로 유지됩니다.
레거시 최상위 openrouter 블록(baseUrl, translationModels, defaultModel, fallbackModel, maxTokens, temperature, requestTimeout, requestTimeoutMs 포함)은 여전히 허용되며, 로드 시 providers.openrouter(provider: "openrouter" 포함)로 자동 마이그레이션됩니다. defaultModel / fallbackModel는 translationModels로 병합됩니다.
하나의 설정에서 여러 프로바이더를 구성하고 -P로 전환하는 실행 가능한 예제는 examples/multi-provider를 참조하세요(openai, anthropic, openrouter, deepseek가 동일한 문서에 있습니다).
여러 모델을 사용하는 이유: 공급자와 모델마다 비용이 다르며 언어 및 로케일에 따라 제공하는 품질 수준도 다양합니다. translationModels을(를) 순서가 지정된 대체 체인으로 구성하여 요청이 실패할 경우 CLI가 다음 모델을 시도하도록 하세요. 해당 목록을 빌드하는 가이드는 AI 모델입니다.
아래 목록을 기준으로 삼으세요. AI 모델의 벤치마크 순위를 참조하여 목록을 교체하세요. 특정 로케일의 번역 품질이 계속 낮은 경우 해당 언어 또는 스크립트에 대한 localeModels 항목을 추가하거나 공급자 카탈로그에서 ID를 더 추가하세요.
이 모델 ID는 ai-i18n-tools init -P openrouter가 작성하는 것입니다. 다른 사전 설정은 init -P <provider>에서 기본 모델 ID를 가져옵니다. — 내장 제공자를 참조하세요.
이 목록은 36개의 대상 로케일을 포함하는 대규모 문서 프로젝트에서 광범위한 로케일 커버리지 테스트를 거쳤습니다. 실용적인 기본값으로 사용되지만, 모든 로케일에서 항상 우수한 성능을 보장하지는 않습니다.
translationModels 예시 (ai-i18n-tools init -P openrouter의 OpenRouter 목록):
OpenRouter translationModels 목록
"translationModels": [
"google/gemini-2.5-flash",
"meta-llama/llama-3.3-70b-instruct",
"openai/gpt-4o-mini",
"google/gemma-4-26b-a4b-it",
"~anthropic/claude-haiku-latest",
"z-ai/glm-5.2",
"google/gemini-3.5-flash",
"~anthropic/claude-sonnet-latest"
// … add more fallback models as needed
]권장 uiModels: UI 문자열은 짧지만 매우 눈에 띕니다. 프리미엄 모델을 사용하면 어조, 복수형 및 일관성이 향상되는 경우가 많습니다. 선택적 uiModels은(는) 일치하는 localeModels 항목 이후, translationModels 이전에 시도됩니다(위의 필드 목록 참조). 예시:
UI 번역을 위한 권장 uiModels
"uiModels": [
"~anthropic/claude-sonnet-latest",
"z-ai/glm-5.2"
]아시아 언어에 대한 권장 localeModels: 일본어, 한국어 및 중국어 로케일은 해당 스크립트에 맞게 조정된 모델을 사용할 때 이점이 있는 경우가 많습니다. 대상 로케일이 일치할 때 먼저 시도되는(uiModels / translationModels 이전) 로케일별 재정의를 추가하세요:
ja, ko, zh-Hans, zh-Hant에 대한 권장 localeModels
"localeModels": [
{ "locale": "ja", "models": [ "z-ai/glm-5.2", "minimax/minimax-m2.7" ] },
{ "locale": "ko", "models": [ "z-ai/glm-5.2", "minimax/minimax-m2.7" ] },
{ "locale": "zh-Hans", "models": [ "z-ai/glm-5.2", "minimax/minimax-m2.7" ] },
{ "locale": "zh-Hant", "models": [ "z-ai/glm-5.2", "minimax/minimax-m2.7" ] }
]활성 프로바이더의 API 키 환경 변수를 환경 또는 .env 파일에 설정하세요(프리셋 테이블 참조).
모델 목록을 변경하기 전에 ai-i18n-tools check-models을 실행하세요. 모든 프로바이더에 대해 구성된 각 모델 ID(translationModels, uiModels 및 모든 localeModels 항목)를 해당 프로바이더의 라이브 모델 목록(GET /models)과 대조하여 검증하고, 누락되었거나 expiration_date가 지난 ID를 보고하며, 유효한 모델을 나열하고, 구성된 ID가 유효하지 않으면 0이 아닌 값으로 종료합니다. 프로바이더가 가격 정보를 반환하는 경우(예: OpenRouter) 입력/출력 가격 추정치(1M 토큰당 USD)도 표시합니다.
구성된 모델을 실제 번역 작업과 비교하려면 ai-i18n-tools bench-models을 실행하세요. translationModels, uiModels, localeModels의 모든 고유 모델 ID를 격리로 번역하여 벤치마킹하고(동시에 실행, concurrency 제한) 모델당 입력/출력 토큰, 경과 시간, USD 비용을 출력하므로 모델 목록을 결정하기 전에 속도와 가격을 비교할 수 있습니다.
features
| 필드 | 파이프라인 | 설명 |
|---|---|---|
translateUIStrings | 1 | t("…") / i18n.t("…")를 strings.json로 추출한 다음, 항목을 번역하고 로케일별 플랫 JSON을 작성합니다(추출은 자동으로 실행됩니다. 카탈로그만 새로 고치려면 독립형 extract를 사용하세요). |
translateDocs | 2 | .md / .mdx / .astro / .html / .htm 페이지 번역; docs[].docusaurusCatalogDir 설정 시 Docusaurus 셸 JSON; 구성 시 Nextra _meta / 사전; docsOutput.vitepressThemeCatalog 설정 시 VitePress 테마; docsOutput.style이(가) "fumadocs"일 때 Fumadocs meta.json / UI 카탈로그. |
translateJson | 3 | json[] 아래의 임의의 중첩된 JSON (translate-json). |
translateSVG | — | .svg 파일 번역 (최상위 svg 블록 필요). |
키가 생략되면 각 플래그는 기본적으로 true입니다. 동작은 다음과 같습니다:
- 번역할 내용이 없는 생략된
true는 건너뛰어집니다: UI 블록에sourceRoots이 없거나, 문서 블록에contentPaths또는docusaurusCatalogDir이 없거나,json[]에contentPaths가 없거나,svg가 설정되지 않은 경우. - 해당 파이프라인에 작업이 없을 때 플래그를
true로 작성하는 것은 구성 오류입니다. false를 작성하면 소스가 존재하더라도sync에 대한 해당 파이프라인이 꺼집니다.--no-ui,--no-docs,--no-json,--no-svg는 한 번의 실행에 대해 단계를 건너뜁니다.
features.translateSVG이(가) true이고 최상위 svg 블록이 구성된 경우 translate-svg을(를) 사용하여 SVG 파일을 번역합니다. 플래그가 켜져 있고 svg이(가) 설정되어 있으면(단, --no-svg인 경우 제외) sync 명령이 해당 단계를 실행합니다.
ui
카탈로그 객체 하나 또는 카탈로그 블록의 배열입니다(docs[]과(와) 같은 개념). 객체 하나를 지정해도 로드 시 요소가 하나인 배열로 래핑되어 처리되며, 디스크에 있는 파일은 다시 쓰이지 않습니다. 파싱 후에는 config.ui이(가) 항상 배열입니다.
extract, translate-ui, sync-ui, sync의 UI 단계, proofread-ui, export-ui-xliff, generate-ui-languages, purge-locale은(는) sourceRoots이(가) 있는 모든 블록을 순회합니다. 블록 하나만 실행하려면 --ui-block에 0부터 시작하는 인덱스, 블록의 description 또는 stringsJson 경로를 전달하십시오. status 및 statistics은(는) 소스가 있거나 기존 카탈로그가 있는 모든 블록을 나열합니다. 번역 대시보드는 이러한 카탈로그를 모두 나열하며, 둘 이상이면 선택기를 표시합니다.
확인된 stringsJson, flatOutputDir 및 매니페스트 경로는 블록 간에 고유해야 합니다. description 값은 설정하는 경우 고유해야 하며, --ui-block이(가) 해당 값을 정확히 일치시켜 찾기 때문입니다.
description구성 파일을 읽는 사람을 위한 선택적 메모입니다(모델로 전송되지 않음). 명령 헤더,status,statistics및 대시보드에ui[i] — description(으)로 표시됩니다.sourceRootst("…")호출을 검색할 디렉터리 또는 glob 패턴입니다(cwd 기준 상대 경로).src/또는["src/**/*.ts"]과(와) 같은 패턴을 지원합니다. 목록이 비어 있는 블록은 건너뛰지만,--ui-block이(가) 해당 블록을 지정하면 오류가 발생합니다.stringsJson이 블록의 마스터 카탈로그 파일 경로입니다.extract에 의해 업데이트됩니다.flatOutputDir이 블록의 로캘별 JSON 파일이 기록되는 디렉터리입니다(de.json등).flatOutputtrue일 때 (기본값),translate-ui는 로케일당 하나의 플랫 JSON 파일을 작성합니다. gettext 또는 resx만 내보내려면false을(를) 설정하세요.flatOutput: false가 있는 블록은gettext또는resx을(를) 설정해야 합니다.resx선택적 .NET.resx출력.outputDir(기본값Resources) 및baseName(기본값SharedResource)은(는){baseName}.resx과(와){baseName}.{culture}.resx를 작성합니다.writeNeutral(기본값 true)는ResourceManager이(가) 대체할 수 있도록 원본 텍스트를 중립 파일에 넣습니다.localeFormat은(는)bcp47(기본값,pt-BR) 또는posix(pt_BR)입니다.ingestExistingResx(기본값 true)는extract동안 위성 어셈블리를 읽습니다.neutralFile는LoginButton와(과) 같은 레거시 명명 키를 중립 값을 통해 매핑합니다. 컨텍스트 키는 U+2404를 사용합니다. 복수형은{singular}[{form}]이라는 별도의 항목입니다.flatOutput: false이(가) 있는 블록은gettext또는resx을(를) 설정해야 합니다.gettext이 블록에 대한 선택적 GNU gettext 출력.outputDir(기본값./locales)은(는)<locale>/LC_MESSAGES/<domain>.po을(를) 받으며,compileMo가 true(기본값)일 때 일치하는.mo를 받습니다.domain의 기본값은messages입니다.potPath은(는) 템플릿 카탈로그입니다.ingestExistingPo(기본값true)은(는)extract동안 비어 있는strings.json슬롯을 비퍼지(non-fuzzy)msgstr값으로 채우며, 비어 있지 않거나 사용자가 편집한 번역은 대체하지 않습니다.localeFormat은(는)posix(기본값,pt_BR) 또는bcp47(pt-BR)입니다. 컨텍스트 행은 gettext\u0004구분 기호를 사용합니다. 두 컨텍스트에서 동일한 원본 언어 문자열은 카탈로그 ID를 공유하지 않습니다.targetLocales이 블록에 대한 선택적 로케일 목록. 생략되거나 비어 있는 경우, 블록은 루트targetLocales을(를) 사용합니다.languagesManifestPathextract및generate-ui-languages가 이 블록의ui-languages.json을(를) 작성하는 선택적 경로. 생략되면 블록 0은 루트languagesManifestPath를 사용하며 (이는 이 블록의{flatOutputDir}/ui-languages.json로 기본 설정됨), 이후 블록은{flatOutputDir}/ui-languages.json으로 기본 설정됩니다.uiGlossarytrue일 때 (기본값), 이 블록의strings.json는translate-docs,translate-json및translate-svg에 대한 용어집 힌트 소스입니다.translate-ui,proofread-ui및 소스 린팅은glossary.userGlossary만 사용합니다. 카탈로그를 해당 힌트에서 제외하려면false을(를) 설정하세요 (예: 문서에 영향을 주지 않아야 하는 CLI 문자열 카탈로그).uiExtractor.funcNames(또는 레거시reactExtractor.funcNames) 스캔할 추가 함수 이름 (기본값:["t", "i18n.t"]).uiExtractor.extensions(또는 레거시reactExtractor.extensions) 포함할 파일 확장자 (기본값:[".js", ".jsx", ".ts", ".tsx"]). Astro 프런트매터 및 템플릿 표현식을 위해.astro을(를) 추가하세요.uiExtractor.includePackageDescription(또는 레거시reactExtractor.includePackageDescription)true일 때 (기본값),extract은(는)package.jsondescription가 존재할 경우 UI 문자열로도 포함합니다. 모든 카탈로그에 동일한 설명이 추출되지 않도록 추가 블록에false을(를) 설정하세요.uiExtractor.packageJsonPath(또는 레거시reactExtractor.packageJsonPath) 해당 선택적 설명 추출에 사용되는package.json파일의 사용자 지정 경로.uiExtractor.includeUiLanguageEnglishNames(또는 레거시reactExtractor.includeUiLanguageEnglishNames)
true일 때 (기본값 false), extract는 번들된 UI 언어 마스터 카탈로그(sourceLocale + 블록의 유효 targetLocales로 빌드됨)에서 각 englishName을 소스 스캔에서 아직 존재하지 않는 경우 (동일한 해시 키) strings.json에 추가합니다. languagesManifestPath을 읽지 않습니다.
uiExtractor.placeholderStyledefault(머스테치, Python 형식 필드 및 printf) 또는dotnet({0},{0,-10},{0:format}만 해당).dotnet스타일에서는 퍼센트 기호가 리터럴 텍스트이고 이중 중괄호는 리터럴 중괄호입니다.ui-dotnet템플릿은dotnet을 설정합니다.uiExtractor.exclude프로젝트 루트를 기준으로 하는 미니매치 패턴은 스캔 후 삭제됩니다.bin,obj,.vs,TestResults및packages는 디렉터리 이름으로 이미 건너뛰어집니다.ui-dotnet및ui-dotnet-resx템플릿은**/Tests/**,**/*.Tests/**및**/TrExtension.cs을 제외합니다.
glossary.uiGlossary 및 glossary.uiGlossaryFromStringsJson은(는) 더 이상 허용되지 않습니다. 구성 로드가 실패하며, 오류 메시지에 대체 방법이 안내됩니다. 해당 키를 삭제하십시오. 이제 힌트는 각 블록의 uiGlossary 플래그(기본값 true)에서 가져옵니다.
cacheDir
cacheDirSQLite 캐시 디렉터리(모든docs블록이 공유). 기본값.translation-cache. 실행 간에 재사용됩니다. 사용자 지정 문서 번역 캐시에서 마이그레이션하는 경우, 해당 캐시를 보관하거나 삭제하십시오.cacheDir은 자체 SQLite 데이터베이스를 생성하며 다른 스키마와 호환되지 않습니다.suggest-models는 벤치마크 집계도<cacheDir>/benchmark-scores.json에 저장합니다. 해당 파일은 디렉터리의 나머지 부분과 마찬가지로 캐시이며, 게시된 패키지의 일부가 아닙니다.
git 제외를 위한 모범 사례:
- 번역 캐시 폴더의 내용을 제외합니다(예:
.gitignore또는.git/info/exclude사용). 이는 임시 캐시 아티팩트가 커밋되는 것을 방지하기 위함입니다. cache.db를 유지합니다(정기적으로 삭제하지 마십시오). SQLite 캐시를 보존하면 변경되지 않은 세그먼트를 다시 번역하는 것을 방지할 수 있기 때문입니다. 이는ai-i18n-tools을 사용하는 소프트웨어를 업데이트하거나 수정할 때 런타임 및 API 비용을 모두 절약해 줍니다.- 비밀 정보와 백업이 커밋되지 않도록 환경 파일 및 임시 파일을 제외합니다.
예시:
init는 기본 cacheDir에 대해 이 블록을 작성합니다. cacheDir가 다를 경우, 두 캐시 라인은 해당 디렉터리를 사용합니다. 예를 들어 .i18n-cache/* 및 !.i18n-cache/cache.db와 같이.
# Cache
.translation-cache/*
!.translation-cache/cache.db
benchmark-scores.json
# Environment
.env
.env.local
.env.*.local
# Temporary files
*.tmp
*.backup.*docs
문서 파이프라인 블록 배열. translate-docs 및 sync의 문서 단계는 각 블록을 순서대로 처리합니다. 레거시 키는 로드 시 여전히 허용되며 구성 파일을 쓸 수 있을 때 다시 작성됩니다. 새 구성에서는 현재 이름을 선호합니다.
| 레거시 키 | 현재 키 / 동작 |
|---|---|
documentations | docs |
markdownOutput | docs[].docsOutput |
jsonSource | docs[].docusaurusCatalogDir |
최상위 openrouter | providers.openrouter + provider: "openrouter" |
features.translateMarkdown | features.translateDocs |
features.translateJSON | 제거됨(docs[].docusaurusCatalogDir 또는 json[] 사용) |
features.extractUIStrings | 제거됨(extract은 UI 번역 전에 실행됨) |
glossary.uiGlossary 및 glossary.uiGlossaryFromStringsJson | 제거됨; 구성 로드 실패. ui[].uiGlossary 사용(부울, 기본값 true) |
ui.reactExtractor | ui.uiExtractor(별칭은 여전히 허용됨) |
svg.svgExtractor.forceLowercase | svg.forceLowercase |
콘텐츠 소스
description이 블록에 대한 선택적 인간이 읽을 수 있는 메모(번역에는 사용되지 않음). 설정 시translate-docs🌐제목 앞에 접두사로 붙으며,status섹션 헤더에도 표시됩니다.contentPaths번역할 Markdown/MDX 페이지 본문 및.astro템플릿(translate-docs는.md,.mdx,.astro를 검색함). 디렉터리 경로 또는 glob 패턴을 지원합니다(예:"docs/**/*.md","guides/*.mdx","src/pages/index.astro"). 이곳이 현지화된 문서 본문의 출처입니다.sourceFiles로드 시contentPaths에 병합되는 선택적 별칭입니다.targetLocales이 블록에만 적용되는 선택적 로케일 하위 집합(그렇지 않으면 루트targetLocales사용). 유효한 문서 로케일은 모든 블록의 합집합입니다.docusaurusCatalogDir선택 사항입니다. 이 블록에 대한 Docusaurus JSON 레이블 카탈로그의 소스 디렉터리(예:docusaurus write-translations의"i18n/en"). 페이지 본문은 항상contentPaths에서 가져옵니다.docusaurusCatalogDir는 셸/UI JSON만 제공하며 MDX는 제공하지 않습니다.nextraMetaGlobdocsRoot아래 Nextra_meta.ts/_meta.tsx/_meta.js에 대한 선택적 glob입니다.docsOutput.style이"nextra"이고 이 항목이 생략되면docsRoot아래의 모든_meta파일이 자동으로 수집됩니다.nextraMetaTranslatableKeysNextra_meta개체에서 문자열 값이 번역되는 선택적 속성 이름(기본값:title,display,breadcrumb).nextraDictionaryPath선택적 영어 Nextra 테마 사전 모듈(예:"app/_dictionaries/en.ts").translate-docs중에{dir}/{locale}.ts로 번역됩니다.nextraDictionaryOutputTemplate로케일 사전 모듈에 대한 선택적 출력 템플릿(기본값: 사전 디렉터리를 기준으로{dir}/{locale}.ts).
docsOutput
이 블록의 출력 레이아웃입니다.
outputDir이 블록에 대한 번역된 출력의 루트 디렉터리입니다.docsOutput.style"nested"(기본값),"flat","doc-system"또는 별칭"docusaurus"/"astro-starlight"/"vitepress"/"nextra".docsOutput.localeSubpathdoc-system에 대한{locale}/과{relativeToDocsRoot}사이의 경로 세그먼트(style: "doc-system"을 직접 사용하는 경우 필수, 별칭을 사용하는 경우 사전 설정). Starlight 스타일 로케일 폴더에는""를 사용합니다.docsOutput.docsRootDocusaurus 레이아웃의 소스 문서 루트(예:"docs"). 생략 시 기본값은"docs"입니다.docsOutput.pathTemplate사용자 지정 마크다운 출력 경로. 자리 표시자:"{outputDir}","{locale}","{LOCALE}","{llocale}","{relPath}","{stem}","{basename}","{extension}","{docsRoot}","{relativeToDocsRoot}".docsOutput.jsonPathTemplate레이블 파일에 대한 사용자 지정 JSON 출력 경로.pathTemplate와 동일한 자리 표시자를 지원합니다.docsOutput.localePathLowercasetrue인 경우, 내장 출력 레이아웃(nested,flat,doc-system(pathTemplate없음))은 경로에 소문자 로케일 세그먼트를 사용합니다. 기본값은false입니다.astro-starlight및doc-system은 빈localeSubpath와 함께 구성 로드 시 기본값으로true을 사용합니다.docsOutput.flatPreserveRelativeDirdocsOutput.style = "flat"인 경우, 동일한 기본 이름을 가진 파일이 충돌하지 않도록 소스 하위 디렉터리를 유지합니다. 기본값은false입니다.docsOutput.rewriteRelativeLinks번역 후 상대 링크를 다시 작성합니다 (docsOutput.style = "flat"이고 사용자 지정pathTemplate가 없을 때 자동 활성화됨).docsOutput.linkRewriteDocsRoot플랫 링크 다시 쓰기 접두사를 계산할 때 사용되는 저장소 루트입니다. 번역된 문서가 다른 프로젝트 루트 아래에 있지 않는 한 일반적으로"."로 둡니다.docsOutput.rewriteVitepressLinkstrue일 때, 번역 후 VitePress 링크 정규화 도구를 실행합니다.docsOutput.style이(가)"vitepress"일 때 기본적으로 활성화됩니다.docsRoot아래의 원본 로케일 파일 옆에 로케일 폴더가 있는 모든doc-system레이아웃과 함께 사용하세요. 원본 언어는sourceLocale이며 모든 언어가 될 수 있습니다. README 스타일docs/guide/…경로를 사이트 경로(/guide/…) 및 로케일 상대../guide/…링크로 다시 작성합니다. VitePress 트리 외부의 저장소 파일(LICENSE,examples/)에 대한 링크의 경우, 원본 로케일 파일에 전체 URL을 사용하세요 — VitePress 통합 — 문서 홈페이지로서의 README를 참조하세요.docsOutput.rewriteNextraLinkstrue일 때, 번역 후 Nextra 링크 정규화 도구를 실행합니다.docsOutput.style이(가)"nextra"일 때 기본적으로 활성화됩니다. Next.jsi18n의content/en/…및 상대.mdx경로를 로케일 중립 사이트 경로(/guide/…)로 다시 작성합니다. Nextra 통합 — 링크 규칙을 참조하세요.docsOutput.fumadocsParser"dot"(기본값) 또는"dir". Dot은 원본 로케일 파일 옆에stem.{locale}.mdx을(를) 작성하고, dir은 Nextra처럼 로케일 폴더를 작성합니다. 원본 언어는sourceLocale이며 모든 언어가 될 수 있습니다. Fumadocs 통합 — 페이지 레이아웃을 참조하세요.docsOutput.rewriteFumadocsLinkstrue일 때, 번역 후 Fumadocs 링크 정규화 도구를 실행합니다.docsOutput.style이(가)"fumadocs"일 때 기본적으로 활성화됩니다. 콘텐츠 경로 및 상대.mdx링크를/docs/…경로로 다시 작성합니다.docsOutput.fumadocsUiCatalog선택 사항입니다.translate-docs내의 Fumadocs UI 재정의 카탈로그 부트스트랩 + 번역. 필드:sourcePath(예:lib/layout.shared.ts),catalogPath(생성된 영어 JSON), 선택 사항인outputPathTemplate(기본값:catalogPath옆의ui.{locale}.json).docs[].fumadocsMetaGlobdocsOutput.style이(가)"fumadocs"일 때meta.json컬렉션을 위한 선택적 glob(들). 기본값:docsOutput.docsRoot아래의 재귀적meta.json.docs[].fumadocsMetaTranslatableKeysFumadocsmeta.json에서 문자열 값이 번역되는 속성 이름입니다(기본값:title,description).docsOutput.localizedAssets로캘 파일이 존재할 경우 번역된 HTML 내 이미지 및 아이콘 URL의 선택적 이름 변경입니다. 필드:include(기본값img/**),pattern(기본값{stem}-{locale}{ext}),onlyIfExists(기본값true),assetRoot(루트 상대 URL 테스트에 사용되는 디렉터리, 기본값은 HTML 파일의 디렉터리). 자리 표시자:{stem},{ext},{basename},{locale},{llocale},{LOCALE}. CSSurl()은(는) 재작성되지 않습니다. HTML 페이지를 참조하세요.docsOutput.htmlHTML 문서를 위한 선택적 언어 목록 및 hreflang입니다. 기본 주석은<!-- ai-i18n:lang-list -->…<!-- /ai-i18n:lang-list -->및<!-- ai-i18n:hreflang -->…<!-- /ai-i18n:hreflang -->입니다.languageList.format은(는)links또는select입니다.languageList.label은(는)local,english또는both입니다.hreflang.siteUrl은(는) 대체 링크에 접두사를 추가하며, 생략 시 링크는 상대 경로로 설정되고 경고가 로그에 기록됩니다.hreflang.xDefault의 기본값은sourceLocale입니다.hreflang.stripIndexHtml은(는)index.html을(를) 디렉터리 URL로 변환합니다. HTML의 경우 로캘 폴더가 추가되기 전에docsRoot이(가) 제거됩니다(docsRoot이(가)site일 때site/index.html→site/{locale}/index.html). HTML 페이지를 참조하세요.docsOutput.vitepressThemeCatalog선택 사항입니다.translate-docs내부에서 VitePress 테마/탐색/사이드바 카탈로그 부트스트랩 및 번역을 수행합니다. 필드:configPath(테마 문자열이 포함된 VitePress 구성),catalogPath(생성된 영어 중첩 JSON), 선택적outputPathTemplate(기본값:catalogPath옆의theme.{locale}.json).
후처리
docsOutput.postProcessing번역된 마크다운 본문에 대한 선택적 변환입니다 (YAML 키와 비산문 프론트 매터 값은 보존됩니다). 세그먼트 재조립 및 링크 재작성(flat 또는 VitePress) 이후,addFrontmatter이전에 실행됩니다.docsOutput.postProcessing.regexAdjustments{ "description"?, "search", "replace" }의 정렬된 목록입니다.search는 정규식 패턴입니다 (일반 문자열은 플래그g를 사용하거나/pattern/flags를 사용합니다).replace는${translatedLocale},${sourceLocale},${sourceFullPath},${translatedFullPath},${sourceFilename},${translatedFilename},${sourceBasedir},${translatedBasedir}와 같은 플레이스홀더를 지원합니다.docsOutput.postProcessing.languageListBlock{ "start", "end", "separator", "label"? }— 소스 및 번역된 마크다운에서 제한된 "다른 언어로 읽기" 링크 행을 재생성합니다.label: "local"일 때 고유어 라벨을 위해languagesManifestPath(또는ui.flatOutputDir/ui-languages.json의 매니페스트)가 필요합니다.
동작 및 메타데이터
translateFrontmatterFieldsdocsOutput과(와) 동일한 수준입니다 (docs[]블록당). 기본값true: Starlight/Docusaurus용 사용자 대면 YAML 산문(프론트 매터)을 번역합니다 (title,description,sidebar.label,sidebar_label,keywords,hero.title,hero.tagline,hero.image.alt,hero.actions[].text,pagination_label,prev/next레이블). 전체 프론트 매터 블록을 변경하지 않으려면false으로 설정하십시오. 특정 점 경로(dot-paths)로 제한하려면 문자열 배열을 전달하십시오.segmentSplittingdocsOutput과(와) 동일한 수준입니다 (docs[]블록당).translate-docs추출을 위한 선택적 세분화된 세그먼트:{ "enabled", "maxCharsPerSegment"?, "splitPipeTables"?, "splitDenseParagraphs"?, "maxLinesPerParagraphChunk"?, "splitLongLists"?, "maxListItemsPerChunk"?, "qualityRetrySplit"?, "maxQualityRetrySplitDepth"? }.enabled이(가)true일 때 (segmentSplitting이(가) 생략된 경우 기본값), 밀집된 단락, GFM 파이프 테이블(첫 번째 청크에는 헤더, 구분 기호 및 첫 번째 데이터 행이 포함됨) 및 긴 목록이 분할됩니다. 하위 부분은 단일 새 줄 문자(tightJoinPrevious)로 다시 결합됩니다. 공백 줄로 구분된 본문 블록당 하나의 세그먼트만 사용하려면"enabled": false으로 설정하십시오.qualityRetrySplit이(가)true일 때 (기본값), 모델 목록이 중지된 후 AST 유효성 검사에 실패한 마크다운 세그먼트는 점진적으로 분할되고 첫 번째 모델부터 다시 시도됩니다. 동일한 품질 오류가 세 번 발생하면 목록이 조기에 중지됩니다.maxQualityRetrySplitDepth(기본값3)은 재귀적 분할을 제한합니다.warnMarkdownSourceIssuestrue일 때 (생략된 경우 기본값), 각translate-docs실행은 위험한 구분 기호/닫히지 않은 인라인 코드를 찾기 위해 마크다운 세그먼트를 다시 스캔하고, 터미널 경고를 출력하며, 해당 파일의 캐시 파일 경로에 대한markdown_source_issues행을 바꿉니다. 이 블록에 대한 경고 및 SQLite 업데이트를 건너뛰려면false으로 설정하십시오.addFrontmattertrue일 때 (생략된 경우 기본값), 번역된 마크다운 파일에는 YAML 키인translation_last_updated,source_file_mtime,source_file_hash,translation_language,source_file_path가 포함되며, 하나 이상의 세그먼트에 모델 메타데이터가 있는 경우translation_models(활성 공급자의 모델 ID 정렬 목록)도 포함됩니다. 건너뛰려면false으로 설정하십시오.emphasisPlaceholdersdocs[]블록당.true일 때, 번역 전에 마크다운 강조 구분 기호를 플레이스홀더로 마스킹합니다. CJK 로케일 (zh,ja,ko) 및rtlLocales에 나열된 로케일의 경우 기본값은true입니다. 그렇지 않으면 기본값은false입니다. CLI--emphasis-placeholders/--no-emphasis-placeholders를 통해 재정의할 수 있습니다.rtlLocales강조 플레이스홀더 기본값에 대해 RTL로 처리되는 BCP-47 코드의 선택적 배열 (내장 RTL 감지와 병합됨).
protectAttributes선택 사항입니다. 따옴표로 묶인 문자열 값이 번역기로 전송되지 않아야 하는 추가 JSX/HTML 속성 이름입니다. 기본 제공되는 기본값(class,id,style,src,href,type,data-*, 대부분의aria-*등)과 병합됩니다. 대소문자 구분 없음. 다음에 적용됩니다..astro정적 HTML 태그 및attr=내부의{expression}블록에서 문자열 리터럴을 추출하여 치환하는 경우.- 마크다운/Astro 세그먼트 번역 중 MDX 플레이스홀더 추출 (대문자 JSX 태그의
label,tooltip,aria-label및 해당되는 경우TabItemvalue).
- 마크다운/Astro 세그먼트 번역 중 MDX 플레이스홀더 추출 (대문자 JSX 태그의
예: "protectAttributes": ["variant", "size"]은(는) variant="primary" 내부의 {items.map(...)}이(가) 여러 로케일에서 변경되지 않도록 유지합니다.
번역 가능한 속성(예: "title" 또는 "aria-label")을 영어에서 그대로 복사하고자 할 때 이 목록에 포함시킬 수 있습니다.
protectKeys선택 사항입니다. 템플릿{expression}블록 및 MDX 객체 리터럴 내부(예:label:내부의<Tabs values={[ … ]}>)에서 따옴표로 묶인 문자열 값이 번역되어서는 안 되는 추가 객체 속성 이름입니다. 기본 제공되는 기본값(class,key,id,href,src등)과 병합됩니다. 대소문자 구분 없음.
예: "protectKeys": ["slug", "code"]은(는) { slug: 'getting-started', title: 'Getting started' }을(를) 건너뜁니다 → slug이(가) 보호된 상태에서 title만 번역됩니다.
예시(docsOutput.style = "flat" — 스크린샷 경로 + 선택적 언어 목록 래퍼):
평면 레이아웃 postProcessing 예제(스크린샷 + languageListBlock)
"docsOutput": {
"style": "flat",
"postProcessing": {
"regexAdjustments": [
{
"description": "Per-locale screenshot folders",
"search": "images/screenshots/[^/]+/",
"replace": "images/screenshots/${translatedLocale}/"
}
],
"languageListBlock": {
"start": "<small id=\"lang-list\">",
"end": "</small>",
"separator": " · ",
"label": "local"
}
}
}json
중첩된 JSON 번역 파이프라인의 최상위 배열입니다. features.translateJson가 true일 때만 사용됩니다(translate-json 또는 sync의 JSON 단계). JSON을 참조하세요.
| 필드 | 설명 |
|---|---|
description | CLI / status용 선택적 메모(번역되지 않음). |
contentPaths | 프로젝트 루트 하의 소스 .json 파일, 디렉터리 또는 글로브입니다. 일반적인 i18next 네임스페이스 파일(public/locales/en/*.json)이 지원됩니다: 중첩 객체, 배열, 문자열 값의 {{var}} 보간, 독립적인 복수 접미사 키(key_one, key_other). |
outputPathTemplate | 대상 로케일별 필수 출력 경로. 자리표시자: {locale}, {LOCALE}, {llocale}, {stem}, {basename}, {extension}, {relativeToSourceRoot}. |
targetLocales | 이 블록에 대한 선택적 하위 집합. 생략 시 루트 targetLocales 사용. |
keyPolicy.mode | allowlist, denylist 또는 both. |
keyPolicy.translateKeys | mode가 allowlist 또는 both일 때 포함할 도트 경로 / glob 패턴. |
keyPolicy.skipKeys | 제외할 도트 경로 / glob 패턴(기본 denylist에는 id, slug, href, url, key, code 포함). |
svg
SVG 파일의 최상위 경로 및 레이아웃입니다. features.translateSVG이 true일 때만 번역이 실행됩니다(translate-svg 또는 sync의 SVG 단계를 통해).
| 필드 | 설명 |
|---|---|
sourcePath | 하나 이상의 디렉터리 또는 glob 패턴 (예: "images/*.svg", "**/icons/*.svg"). 패턴은 프로젝트 루트를 기준으로 상대적으로 해석되며, .svg 파일을 재귀적으로 검색합니다. |
outputDir | 번역된 SVG 출력의 루트 디렉터리입니다. |
style | pathTemplate이 설정되지 않은 경우 "flat" 또는 "nested"입니다. |
pathTemplate | 사용자 지정 SVG 출력 경로. 사용 가능한 자리 표시자: "{outputDir}", "{locale}", "{LOCALE}", "{llocale}", "{relPath}", "{stem}", "{basename}", "{extension}", "{relativeToSourceRoot}". |
localePathLowercase | true인 경우, 기본 제공 flat / nested SVG 레이아웃은 소문자 로케일 세그먼트를 사용합니다. 사용자 지정 pathTemplate 값은 변경되지 않으며, 소문자 세그먼트가 필요한 경우 {llocale}을(를) 사용하십시오. |
forceLowercase | SVG 재조합 시 소문자로 변환된 텍스트입니다. 모두 소문자 레이블에 의존하는 디자인에 유용합니다. |
modelSuggestion (선택 사항)
suggest-models 및 대시보드 모델 탭에 적용되는 ChrF 및 Arena 가중치와 선택적 품질 하한선입니다. 인덱스는 품질만을 기준으로 합니다. 해당 블록을 생략하거나 프로필 하나를 생략하면, 해당 프로필은 내장된 가중치를 유지합니다. 해당 블록은 --apply 또는 구성 업데이트에 의해 다시 작성되지 않습니다. 이들은 모델 ID만 작성합니다. 구성이 로드될 때 프로필에 있는 레거시 price 가중치는 제거됩니다.
quality— 기본 ChrF0.55, Arena0.45, 품질 하한선0.7price— 기본 ChrF0.55, Arena0.45, 품질 하한선0.6
각 프로필 객체에는 chrf 및 arena이 필요합니다. 각 값은 유한하며 최소 0 이상이어야 하고, 최소 하나는 0보다 커야 합니다. 이 값들은 합계가 1이 되도록 정규화되므로, 55 및 45는 기본값과 일치합니다. qualityFloor은 선택 사항이며, (0, 1] 범위 내에 있고, 후보 풀에서 가장 좋은 ChrF의 비율을 나타냅니다. 하한선 미만의 모델(ChrF 측정값이 없는 모델 포함)은 하한선을 통과한 모델 뒤에 정렬됩니다. 두 프로필은 동일한 기본 혼합을 공유하지만, 정렬 순서(인덱스 기준 --quality, 파레토 프론티어 기준 --price)와 하한선에서 차이가 있습니다.
"modelSuggestion": {
"quality": { "chrf": 0.55, "arena": 0.45, "qualityFloor": 0.7 },
"price": { "chrf": 0.55, "arena": 0.45, "qualityFloor": 0.6 }
}glossary
| 필드 | 설명 |
|---|---|
userGlossary | 열이 Original language string(또는 en), locale, Translation, 선택 사항인 Force 및 선택 사항인 Context인 CSV 경로 - 소스 용어 및 대상 로캘당 한 행(locale은(는) 모든 대상에 대해 *일 수 있음). |
autoAddUserEditedToGlossary | true일 때, UI 문자열에 대한 대시보드 편집 내용을 사용자 용어집에 자동으로 추가할 수 있습니다. |
contextFiles | 선택적 cwd 상대 경로의 Markdown 또는 일반 텍스트 파일(.md, .markdown, .txt)로, 제품 또는 기능 설명을 포함합니다. 명령 시작 시 로드되어 UI, 문서, JSON, SVG 및 교정 프롬프트에 주입됩니다. 번역도 원할 경우에만 이 파일들을 docs[].contentPaths에 넣으세요. URL은 거부됩니다. 전체 텍스트는 구성된 LLM 프로바이더로 전송되며 --debug-failed 로그에 나타날 수 있으므로 — 비밀이나 PII를 포함하지 마세요. |
contextMaxChars | 모델로 전송되는 결합된 컨텍스트 파일 텍스트의 최대 문자 수(기본값 12000, 하드 캡 100000). 초과 텍스트는 경고와 함께 잘립니다. |
labelCheckSkips | 건너뛸 잠긴 UI 레이블 검사의 선택적 목록입니다. 각 항목에는 term (영어 용어집 용어), locales (대상 코드 또는 모든 로케일에 대한 *; 기본값 *), 선택적 files (cwd-상대 글로브), 그리고 선택적 note이(가) 있습니다. 이 용어는 프롬프트 힌트로 유지됩니다. 건너뛰기는 다음 translate-docs 실행 시 적용됩니다. |
translate-docs, translate-json 및 translate-svg는 uiGlossary이(가) true(기본값)인 각 UI 블록에서도 힌트를 가져옵니다. 이는 해당 블록의 strings.json에 이미 저장된 번역을 재사용합니다. 블록에서 uiGlossary을(를) false(으)로 설정하여 제외할 수 있습니다. translate-ui 및 proofread-ui는 이러한 카탈로그를 힌트로 사용하지 않습니다. 문서 프롬프트가 생성된 {{…}} 토큰으로 유도되지 않도록 간결한 UI 레이블 약어(Alm.과(와) 같은 후행 점 형식 또는 Size → Tam과(와) 같은 짧은 단일 토큰 압축)는 건너뜁니다. 전체 제품 용어 및 약어가 아닌 UI 번역은 여전히 힌트로 제공됩니다.
선택적 Context CSV 열은 해당 용어에 대한 원본 언어 사용 지침(정의, 문법적 사용, 제품 의미)입니다. 이것은 용어가 현재 배치와 일치할 때만 포함됩니다. 용어의 Context 노트 또는 contextFiles 콘텐츠를 변경하면 다음 실행 시 일치하는 로케일의 캐시된 세그먼트 및 파일 추적 행이 무효화되므로 번역이 자동으로 새로 고쳐집니다. 강제되지 않은 행에서 선호하는 Translation만 변경하는 경우에도 --force / --force-update를 전달하지 않으면 기존 캐시를 사용합니다. Force 행은 저장된 텍스트에 강제 번역이 이미 포함되어 있지 않은 경우, 원본에 해당 용어가 포함된 세그먼트만 놓칩니다. 대시보드에서 사용자가 편집한 캐시 행은 유지됩니다. UI 카탈로그는 또한 해당 접두사가 대문자로 시작하는 레이블(최소 두 개의 내용어)이고 공유 번역이 자리 표시자 없는 짧은 구문일 때 공유 다중 단어 접두사를 자체 용어로 시드합니다. 마크다운 번역은 원본이 전체 굵은 글씨 또는 인라인 코드 범위, 제목 또는 해당 레이블만 있는 줄로 인용할 때 카탈로그 번역을 유지하기 위해 2~5단어 UI 레이블이 필요합니다. 단순히 용어를 포함하는 더 긴 굵은 글씨 구문은 힌트입니다. 문장 내의 제목 대소문자는 힌트이므로 번역은 굴절될 수 있습니다 (힌디어 Cursor account은 사전 형태인 कर्सर खाता 대신 कर्सर खाते이 될 수 있습니다). Sign in과(와) 같이 내용어가 하나인 레이블은 힌트로 유지됩니다. 검사는 대소문자를 무시합니다. 여전히 카탈로그 문구를 부분 문자열로 요구하므로 문법적으로 굴절된 형태는 실패할 수 있습니다. 이 실패는 경고입니다. 해당 세그먼트는 작성되고 용어집 레이블 플래그와 함께 캐시되며, 실행 끝에 cacheDir 아래 glossary-review-*.md에 나열됩니다. 검토 후 labelCheckSkips 항목을 추가하거나 --recheck-glossary-warnings를 전달하십시오. --force는 플래그가 지정된 행을 다른 모든 세그먼트와 함께 다시 번역합니다.
예시:
{
"glossary": {
"userGlossary": "i18n/glossary.csv",
"contextFiles": ["i18n/product-context.md", "i18n/billing-feature.md"],
"contextMaxChars": 12000,
"labelCheckSkips": [
{
"term": "Target language",
"locales": ["uk"],
"files": ["website/src/content/docs/docs/transform.md"],
"note": "Inflected inside a bold phrase"
}
]
}
}빈 용어집 CSV 생성:
ai-i18n-tools glossary-generate저장소에서 contextFiles의 초안을 작성하려면 AI 에이전트로 컨텍스트 파일 생성의 복사하여 붙여넣기 에이전트 프롬프트를 사용하십시오. 용어 행 및 컨텍스트 파일이 적용되는 방식은 용어집을(를) 참조하십시오.