UI 문자열
extract 및 translate-ui 참조: t() 호출을 로케일별 카탈로그로 변환하는 파이프라인입니다. 앱에 i18n을 처음 추가하시나요? JS/TS 앱에 i18n 추가, Python 앱에 i18n 추가, 또는 .NET 앱에 i18n 추가에서 시작하세요. 이 문서들은 래핑 단계를 다루며, 이후 2단계부터 4단계까지는 여기로 다시 안내합니다.
이 파이프라인은 JS/TS 프로젝트(React, Next.js 클라이언트 및 서버 컴포넌트, Node.js 서비스, 일반 HTML, Astro 웹사이트 및 CLI 도구), Python 애플리케이션 및 .NET 애플리케이션에 사용됩니다. JS/TS는 소스에서 t()를 호출한 후 i18next로 문자열을 찾습니다. Python은 생성된 i18n.py를 통해 t() 또는 gettext를 호출합니다(Django는 Django의 gettext를 유지합니다). .NET은 생성된 I18n.cs를 통해 T()를 호출합니다.
어떤 가이드를 읽어야 할까요?
| 사용 중인 앱 | 다음에 읽을 문서 |
|---|---|
하드코딩된 소스 문자열이 있고 아직 t()가 없는 JS/TS | JS/TS 앱에 i18n 추가 |
소스에 t()가 이미 있는 React / Next.js / Node | i18next 연결 |
Python (t(), _(), gettext, Jinja, Django) | 파이썬 애플리케이션. 초기화: ui-python, ui-python-gettext, ui-python-flask, 또는 ui-python-django. 도우미: i18n.py. 기존 앱에 로케일을 추가하려면 파이썬 앱에 i18n 추가를 참조하거나, 앱이 gettext를 사용하는 경우 Django / 파이썬 gettext 앱에 i18n 추가를 참조하십시오. |
.NET (T(), Tn, Tp, XAML loc:Tr) | .NET 애플리케이션. 초기화: ui-dotnet (I18n.cs) 또는 ui-dotnet-resx (.NET ResourceManager 앱에 i18n 추가). 기존 앱에 로케일을 추가하려면 .NET 앱에 i18n 추가를 참조하세요. |
일반 HTML (마크업에 t() 없음) | 일반 HTML 앱 |
| Astro 마케팅 사이트 (하이브리드) | Astro 웹사이트 |
t() 규칙, 보간, 복수 | t() 호출 및 복수 |
| 언어 선택기 / RTL | 언어 전환기 및 RTL |
| 런타임 API 서명 | 런타임 도우미 |
Intlayer에서 마이그레이션하는 Intlayer .content.ts 사전 | Intlayer에서 마이그레이션 |
Intlayer를 유지하는 Intlayer .content.ts 사전 | Intlayer 인플레이스 번역 |
1단계: 초기화
ai-i18n-tools init -P openrouter이것은 ui-markdown 템플릿으로 ai-i18n-tools.config.json를 작성합니다(해당 프리셋에 대한 provider / providers 블록 포함). 해당 템플릿은 또한 README.md에 대한 문서 번역을 활성화하며, translated-docs/ 아래에 플랫 파일로 작성됩니다. README 전용 리포지토리는 대신 init -t docs-markdown를 사용합니다. README 및 Markdown 문서에 i18n 추가를 참조하세요. translate-ui 또는 sync를 실행하기 전에, 해당 공급자의 API 키를 환경 또는 .env에 설정하세요 — Ollama는 예외입니다. 공급자 및 API 키를 참조하세요. UI 문자열에는 네 가지 키가 중요합니다.
sourceLocale: 소스 텍스트가 작성된 언어의 BCP-47 코드입니다. 모든 언어가 유효하며,"en-GB"는 예시일 뿐입니다. 런타임 i18n 설정 파일(src/i18n.ts/src/i18n.js)에서 내보낸SOURCE_LOCALE와 일치해야 합니다.t()안의 문자열은 해당 소스 언어이며, 플랫 로캘 파일은 이를 키로 사용합니다.targetLocales: 대상 언어의 BCP-47 코드입니다(예:["de", "fr", "pt-BR"]).generate-ui-languages를 실행하여 이 목록에서ui-languages.json매니페스트를 생성합니다.ui.sourceRoots:t("…")호출을 스캔할 디렉터리 또는 glob 패턴입니다(예:["src/"]).ui.stringsJson및ui.flatOutputDir: 마스터 카탈로그와 로캘별 파일(de.json,pt-BR.json)이 작성되는 위치입니다.
providers.<active>.uiModels를 포함한 다른 모든 키는 구성에 있습니다.
2단계: 문자열 추출
t() / i18n.t() 호출이 존재할 때까지 extract는 유용한 작업을 수행하지 않습니다. 먼저 하드코딩된 사본을 래핑하세요: JS/TS 앱에 i18n 추가.
ai-i18n-tools extractui.sourceRoots 아래의 파일에서 t("literal") 및 i18n.t("literal") 호출을 스캔합니다. ui.stringsJson에 쓰거나 병합합니다.
스캐너는 구성 가능합니다. ui.uiExtractor.funcNames(또는 레거시 ui.reactExtractor.funcNames)를 통해 사용자 지정 함수 이름을 추가합니다. Astro 페이지 및 구성 요소의 경우 .astro를 ui.uiExtractor.extensions에 추가합니다. 일반 HTML의 경우 일반 HTML 앱을 참조하십시오.
extract가 스캔하는 대상
- 기본 확장자는
.js,.jsx,.ts,.tsx뿐입니다..mjs,.cjs,.mts,.cts는ui.uiExtractor.extensions에 추가할 때만 포함됩니다. t(variable)와 같은 리터럴이 아닌 키 또는 템플릿 리터럴은 경고 없이 건너뜁니다.package.jsondescription는 기본적으로 포함됩니다(ui.uiExtractor.includePackageDescription).- Vue 및 Svelte 단일 파일 컴포넌트는 지원되지 않습니다.
.vue또는.svelte를extensions에 추가해도 템플릿 텍스트가 추출되지 않습니다. SFC 파서가 없습니다.
3단계: UI 문자열 번역
ai-i18n-tools translate-uistrings.json을(를) 읽고, 각 대상 로케일에 대해 활성 LLM 공급자의 모델로 배치를 전송하며, ui.flatOutputDir에 플랫 JSON 파일(de.json, fr.json 등)을 씁니다. 모델 선택은 UI 체인: localeModels(locale) → uiModels → translationModels을(를) 사용합니다(AI 모델 참조). 한 로케일 내에서 최대 uiBatchConcurrency개의 배치가 동시에 실행됩니다(기본값 2; 구성 — uiBatchConcurrency 참조). -j는 여전히 대상 로케일만 병렬 처리합니다. 각 성공적인 배치는 다음 배치가 시작되기 전에 strings.json와 플랫 로케일 파일에 기록되므로, 실행을 중지하거나 나중에 API 오류가 발생해도 이미 완료된 배치는 유지됩니다.
번역 데이터베이스 (strings.json)
각 항목에 대해 translate-ui는 선택적 models 개체(translated와 동일한 로케일 키)에 각 로케일을 성공적으로 번역한 활성 공급자의 모델 ID를 저장합니다. 번역 대시보드에서 편집된 문자열은 해당 로케일에 대해 models에 센티넬 값 user-edited으로 표시됩니다. ui.flatOutputDir 아래의 로케일별 플랫 파일은 원본 문자열 → 번역만 유지하며, models를 포함하지 않습니다(따라서 런타임 번들은 변경되지 않습니다).
참고: UI 문자열에 대한 대시보드 편집 내용은 SQLite 문서 캐시가 아닌
strings.json에 저장됩니다. 카탈로그에서 플랫 로케일 파일을 다시 작성하려면 일반sync또는translate-ui(특수 플래그 없음)를 실행하십시오.--force-update는 UI 단계로 전달되지 않습니다. 수동 편집 후 UI 명령에--force를 사용하지 마십시오. 이는 모든 항목을 다시 번역하고user-edited행을 덮어쓸 수 있습니다. 저장된 번역이 로케일 쓰기 시스템 검사(예:hi에 대한 로마자화된 힌디어)에 실패한 카탈로그 행은 누락된 것으로 간주되어--force없이 다시 번역됩니다.
4단계: 앱에서 출력 사용하기
translate-ui는 파일만 작성합니다. 앱이 파일을 로드해야 합니다.
- JS/TS: 런타임 헬퍼로 i18next를 설정하고, 사용자가 선택한 로케일 파일을 로드하며, 언어 전환기를 추가합니다. i18next 연결 및 언어 전환기 및 RTL을 참조하세요.
- Python: 생성된
i18n.py또는 gettext 카탈로그를 사용합니다. Python 애플리케이션을 참조하세요. - .NET: 생성된
I18n.cs을 사용하거나, 앱이 이미ResourceManager를 사용하는 경우I18nResx.cs를 사용합니다. .NET 애플리케이션 및 .NET ResourceManager 앱에 i18n 추가를 참조하세요.migrate-dotnet-i18n는 안전하지 않은T()인수를 다시 작성합니다.--wrap는 표시되지 않은 레이블을 감사합니다. - 일반 HTML: 페이지 옆에 런타임 스크립트를 로드합니다. 일반 HTML 앱을 참조하세요.
- Astro: Astro 웹사이트를 참조하세요.
선택 사항
로케일별 모델 재정의
일부 모델은 다른 모델보다 특정 언어를 더 잘 번역합니다. 예를 들어, qwen 및 z-ai 모델은 아시아 언어에 강한 경향이 있습니다. 각 BCP-47 로케일에 대한 우선순위 모델 목록을 제공하려면 providers.<active>.localeModels 항목을 추가하십시오. 해당 로케일에 대해 uiModels 및 translationModels보다 먼저 해당 목록이 시도됩니다. 로케일 태그는 대소문자를 구분하지 않습니다(zh-cn와 ZH-CN는 동일합니다). 일치하는 항목이 없으면 도구는 기본 uiModels 및 translationModels 순서를 사용합니다. 동일한 localeModels 메커니즘이 문서, JSON 및 SVG 번역에 적용됩니다.
XLIFF 2.0으로 내보내기
UI 문자열을 번역 업체, TMS 또는 CAT 도구에 넘기기 위해 카탈로그를 XLIFF 2.0 형식으로 내보냅니다(대상 로케일당 하나의 파일). 이 명령은 읽기 전용입니다: strings.json을 수정하거나 API를 호출하지 않습니다.
ai-i18n-tools export-ui-xliff기본적으로 파일은 ui.stringsJson 옆에 strings.de.xliff, strings.pt-BR.xliff(카탈로그의 기본 이름 + 로케일 + .xliff) 형태로 작성됩니다. 다른 위치에 쓰려면 -o / --output-dir를 사용하세요. strings.json의 기존 번역은 <target>에 나타나며, 누락된 로케일은 state="initial"을 사용하고 <target> 없이 표시되어 도구에서 채울 수 있습니다. --untranslated-only을 사용하면 각 로케일별로 아직 번역이 필요한 항목만 내보낼 수 있습니다(업체 배치에 유용함). --dry-run은 파일을 쓰지 않고 경로만 출력합니다.