UI 문자열

i18next를 사용하는 모든 JS/TS 프로젝트에 적합합니다: React 앱, Next.js(클라이언트 및 서버 구성 요소), Node.js 서비스, 평면 HTML, Astro 웹사이트 및 CLI 도구.

어떤 가이드를 읽어야 할까요?

귀하의 앱	다음 읽기
React / Next.js / Node + i18next	i18next 연결 (4단계)
일반 HTML (마크업에 t() 없음)	일반 HTML 앱
Astro 마케팅 사이트 (하이브리드)	Astro 웹사이트
t() 규칙, 보간, 복수	t() 호출 및 복수
언어 선택기 / RTL	언어 전환기 및 RTL
런타임 API 서명	런타임 도우미
Intlayer .content.ts 사전	Intlayer에서 마이그레이션

1단계: 초기화

ai-i18n-tools init [-P <provider>]

이 작업은 기본 provider / providers 블록을 포함하여 ui-markdown 템플릿으로 ai-i18n-tools.config.json를 작성합니다. translate-ui 또는 sync를 실행하기 전에, 환경 변수나 .env에서 활성 프로바이더의 API 키를 설정하세요. 단, Ollama는 예외입니다. 자세한 내용은 프로바이더 및 API 키를 참조하세요. config를 편집하여 다음을 설정하세요:

• provider 및 providers — 최소한 하나의 제공자가 translationModels를 가지고 있습니다; 기본값이 선택 사항이 아닌 경우 프리셋 또는 모델 목록을 변경하십시오 (init -P <provider>). LLM 제공자 및 모델를 참조하십시오.
• sourceLocale - 귀하의 소스 언어 BCP-47 코드 (예: "en-GB"). 일치해야 합니다 SOURCE_LOCALE 귀하의 런타임 i18n 설정 파일에서 내보낸 (src/i18n.ts / src/i18n.js).
• targetLocales - 귀하의 대상 언어에 대한 BCP-47 코드 배열 (예: ["de", "fr", "pt-BR"]). generate-ui-languages을 실행하여 이 목록에서 ui-languages.json 매니페스트를 생성하십시오.
• ui.sourceRoots - t("…") 호출을 스캔할 디렉토리 또는 글로브 패턴 (예: ["src/"], ["src/**/*.ts"]).
• ui.stringsJson - 마스터 카탈로그를 작성할 위치(예: "src/locales/strings.json").
• ui.flatOutputDir - de.json, pt-BR.json 등을 작성할 위치(예: "src/locales/").
• providers.<active>.uiModels (선택 사항) - translate-ui, 복수형 생성 및 proofread-ui을 위한 정렬된 UI 전용 모델 목록(일치하는 localeModels 항목 이후, translationModels 이전). 프로바이더 및 모델을 참조하세요.

2단계: 문자열 추출

ai-i18n-tools extract

ui.sourceRoots 하위의 모든 JS/TS 파일을 스캔하여 t("literal") 및 i18n.t("literal") 호출을 찾습니다. ui.stringsJson에 쓰거나 병합합니다.

스캐너는 구성 가능합니다. ui.uiExtractor.funcNames(또는 레거시 ui.reactExtractor.funcNames)를 통해 사용자 지정 함수 이름을 추가합니다. Astro 페이지 및 구성 요소의 경우 .astro를 ui.uiExtractor.extensions에 추가합니다. 일반 HTML의 경우 일반 HTML 앱을 참조하십시오.

3단계: UI 문자열 번역

ai-i18n-tools translate-ui

strings.json을(를) 읽고, 각 대상 로케일에 대해 활성 LLM 제공자에게 배치를 전송하며, 평면 JSON 파일(de.json, fr.json 등)을 ui.flatOutputDir에 작성합니다. 모델 선택은 UI 체인을 사용합니다: localeModels(locale) → uiModels → translationModels (제공자 및 모델 참조). 로케일 내에서 최대 uiBatchConcurrency개의 배치가 동시에 실행됩니다(기본값 2; 구성 — uiBatchConcurrency 참조). -j은 여전히 대상 로케일만 병렬 처리합니다.

로케일별 모델 재정의

대상 언어에 따라 일부 번역 모델은 다른 모델보다 훨씬 더 우수한 성능을 발휘할 수 있습니다. 예를 들어, qwen 및 z-ai 모델은 많은 서양(Occidental) 언어 모델에 비해 아시아 언어에 대해 더 높은 품질의 번역을 생성하는 경향이 있습니다. 이를 활용하기 위해, 각 BCP-47 로케일에 대해 우선 순위가 지정된 모델 목록을 지정하기 위해 선택적 providers.<active>.localeModels 항목을 사용할 수 있습니다. 이러한 모델 목록은 특정 로케일에 대해 보다 일반적인 uiModels 및 translationModels보다 먼저 시도됩니다. 이를 통해 모델 선택을 조정하고 언어별로 더 나은 번역 품질을 달성할 수 있습니다. 로케일 태그는 대소문자를 구분하지 않고 일치합니다(따라서 zh-cn 및 ZH-CN는 동일합니다). 사용자 인터페이스 번역을 위해 사용자 정의 항목과 일치하는 로케일이 없으면 도구는 기본 uiModels 및 translationModels 순서로 돌아갑니다. 동일한 localeModels 메커니즘은 문서, JSON 및 SVG 번역에도 적용됩니다.

번역 데이터베이스 (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 없이 다시 번역됩니다.

그런 다음 런타임에 i18next를 연결합니다. i18next 연결.

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은 파일을 쓰지 않고 경로만 출력합니다.