ai-i18n-tools 1.0.0

package/translated-docs/README.ja.md

@@ -0,0 +1,157 @@
+# ai-i18n-tools
+
+JavaScript/TypeScript アプリケーションおよびドキュメントサイトの国際化のための CLI およびプログラムによるツールキット。UI 文字列を抽出し、OpenRouter 経由で LLM を使用して翻訳し、i18next 向けのロケール対応 JSON ファイルを生成します。さらに、Markdown、Docusaurus JSON、および（`features.translateSVG`、`translate-svg`、および `svg` ブロックを介して）スタンドアロンの SVG アセット向けのパイプラインも提供します。
+
+**他の言語で読む:**
+
+<small id="lang-list">[en-GB](../README.md) · [de](./README.de.md) · [es](./README.es.md) · [fr](./README.fr.md) · [hi](./README.hi.md) · [ja](./README.ja.md) · [ko](./README.ko.md) · [pt-BR](./README.pt-BR.md) · [zh-CN](./README.zh-CN.md) · [zh-TW](./README.zh-TW.md)</small>
+
+## 2つの主要なワークフロー
+
+**ワークフロー 1 - UI 翻訳** (React, Next.js, Node.js、あらゆる i18next プロジェクト)
+
+ソースファイルをスキャンして `t("…")` 呼び出しを検出し、マスターカタログ（オプションのロケールごとの **`models`** メタデータを含む `strings.json`）を構築し、OpenRouter を介してロケールごとに不足しているエントリを翻訳し、i18next で使用できるフラットな JSON ファイル（`de.json`、`pt-BR.json`、…）を書き出します。
+
+**ワークフロー 2 - ドキュメント翻訳** (Markdown、Docusaurus JSON)
+
+`documentations` ブロックの `contentPaths` にある `.md` および `.mdx` ファイル、およびそのブロックの `jsonSource` にある JSON ラベルファイルを、有効にした場合に翻訳します。ブロックごとに Docusaurus スタイルまたはフラットなロケール接尾辞付きレイアウトをサポート（`documentations[].markdownOutput`）。共有ルートの `cacheDir` に SQLite キャッシュを保持するため、LLM に送信されるのは新規または変更されたセグメントのみです。**SVG：** `features.translateSVG` を有効にし、トップレベルの `svg` ブロックを追加して、`translate-svg` を使用します（両方が設定されている場合、`sync` からも実行されます）。
+
+両方のワークフローは単一の `ai-i18n-tools.config.json` ファイルを共有しており、個別または併用が可能です。スタンドアロンの SVG 翻訳は `features.translateSVG` とトップレベルの `svg` ブロックを使用し、`translate-svg`（または `sync` 内の SVG ステージ）を通じて実行されます。
+
+---
+
+## インストール
+
+公開されているパッケージは **ESM のみ**（`"type": "module"`）です。Node.js、バンドラー、または `import()` から `import` を使用してください — **`require('ai-i18n-tools')` はサポートされていません。**
+
+```bash
+npm install ai-i18n-tools
+# or
+pnpm add ai-i18n-tools
+```
+
+OpenRouter API キーを設定してください：
+
+```bash
+export OPENROUTER_API_KEY=sk-or-v1-your-key-here
+```
+
+---
+
+## クイックスタート
+
+### ワークフロー 1 - UI 文字列
+
+```bash
+# 1. Create config
+npx ai-i18n-tools init
+
+# 2. Extract t("…") calls from source
+npx ai-i18n-tools extract
+
+# 3. Translate to all target locales
+npx ai-i18n-tools translate-ui
+```
+
+`'ai-i18n-tools/runtime'` のヘルパーを使用して、アプリに i18next を組み込みます：
+
+```js
+import i18n from 'i18next';
+import { initReactI18next } from 'react-i18next';
+import uiLanguages from './locales/ui-languages.json';
+import {
+  defaultI18nInitOptions,
+  wrapI18nWithKeyTrim,
+  makeLoadLocale,
+  applyDirection,
+} from 'ai-i18n-tools/runtime';
+
+// Must match sourceLocale in ai-i18n-tools.config.json
+export const SOURCE_LOCALE = 'en-GB';
+
+void i18n.use(initReactI18next).init(defaultI18nInitOptions(SOURCE_LOCALE));
+wrapI18nWithKeyTrim(i18n);
+i18n.on('languageChanged', applyDirection);
+applyDirection(i18n.language);
+
+const localeLoaders = Object.fromEntries(
+  uiLanguages
+    .filter(({ code }) => code !== SOURCE_LOCALE)
+    .map(({ code }) => [code, () => import(`./locales/${code}.json`)])
+);
+export const loadLocale = makeLoadLocale(i18n, localeLoaders, SOURCE_LOCALE);
+export default i18n;
+```
+
+### ワークフロー 2 - ドキュメント
+
+```bash
+# 1. Create config for Docusaurus
+npx ai-i18n-tools init -t ui-docusaurus
+
+# 2. Translate all docs
+npx ai-i18n-tools translate-docs
+
+# 3. Check status
+npx ai-i18n-tools status
+```
+
+### 両方のワークフロー
+
+```bash
+npx ai-i18n-tools sync   # Extract UI strings, then translate UI strings, SVG, and docs
+```
+
+---
+
+## ランタイムヘルパー
+
+`'ai-i18n-tools/runtime'` からエクスポート - あらゆる JS 環境で動作し、i18next のインポートは不要です：
+
+| ヘルパー | 説明 |
+|---|---|
+| `defaultI18nInitOptions(sourceLocale)` | キーをデフォルト値として使用する設定のための標準的な i18next 初期化オプション。 |
+| `wrapI18nWithKeyTrim(i18n)` | キーがルックアップ前にトリミングされるように `i18n.t` をラップします。 |
+| `makeLoadLocale(i18n, loaders, sourceLocale)` | 非同期ロケールファイル読み込みのためのファクトリ関数。 |
+| `getTextDirection(lng)` | BCP-47 コードに対して `'ltr'` または `'rtl'` を返します。 |
+| `applyDirection(lng, element?)` | `document.documentElement` に `dir` 属性を設定します。 |
+| `getUILanguageLabel(lang, t)` | 言語メニュー行の表示ラベル（i18n を使用）。 |
+| `getUILanguageLabelNative(lang)` | `t()` を呼び出さない表示ラベル（ヘッダースタイル）。 |
+| `interpolateTemplate(str, vars)` | プレーン文字列に対する `{{var}}` 置換の低レベル関数（内部で使用されます。アプリコードは代わりに `t()` を使用すべきです）。 |
+| `flipUiArrowsForRtl(text, isRtl)` | RTL レイアウトのために `→` を `←` に反転します。 |
+
+---
+
+## CLI コマンド
+
+```
+ai-i18n-tools init [-t ui-markdown|ui-docusaurus]   Create config file
+ai-i18n-tools extract                               Scan source for t("…") calls
+ai-i18n-tools translate-docs [--locale <code>]      Translate documentation (markdown, JSON); see docs for
+                                                    --force-update, --force, --stats, --clear-cache,
+                                                    --prompt-format (xml | json-array | json-object)
+ai-i18n-tools translate-svg [--locale <code>]       Standalone SVG assets (features.translateSVG + config.svg); see --no-cache
+ai-i18n-tools translate-ui [--locale <code>]        Translate UI strings only; see --force, --dry-run
+ai-i18n-tools export-ui-xliff [--locale <code>]     Export UI strings to XLIFF 2.0 (one file per locale); see --untranslated-only, -o
+ai-i18n-tools sync                                  Extract UI strings, then translate UI strings, SVG, and docs
+ai-i18n-tools status                                Translation status per file × locale
+ai-i18n-tools editor                                Open cache/glossary web editor
+ai-i18n-tools cleanup [--dry-run] [--no-backup] [--backup <path>]   Runs sync --force-update, then cleans stale + orphaned cache rows; backs up SQLite by default
+ai-i18n-tools glossary-generate                     Create empty glossary CSV template
+```
+
+すべてのコマンドは `-c <config>`（デフォルト: `ai-i18n-tools.config.json`）、`-v`（詳細）、およびオプションの `-w` / `--write-logs [path]` を受け入れ、コンソール出力をログファイルに追加します（デフォルト: 翻訳キャッシュディレクトリの下）。
+
+---
+
+## ドキュメント
+
+- [はじめに](docs/GETTING_STARTED.ja.md) - 両方のワークフローの完全なセットアップガイド、すべてのCLIフラグ、および設定フィールドのリファレンス。
+- [パッケージ概要](docs/PACKAGE_OVERVIEW.ja.md) - アーキテクチャ、内部構造、プログラムAPI、および拡張ポイント。
+- [AIエージェントコンテキスト](../docs/ai-i18n-tools-context.md) - コードや設定変更を行うエージェントやメンテナのための簡潔なプロジェクトコンテキスト。
+
+---
+
+## ライセンス
+
+MIT © [ヴァルデマール・スカデラー・ジュニア](https://github.com/wsj-br)

package/translated-docs/README.ko.md

@@ -0,0 +1,157 @@
+# ai-i18n-tools
+
+JavaScript/TypeScript 애플리케이션 및 문서 사이트의 국제화를 위한 CLI 및 프로그래밍 도구모음입니다. UI 문자열을 추출하고 OpenRouter를 통해 LLM을 사용하여 번역한 후 i18next용 로케일 대응 JSON 파일을 생성하며, 마크다운, Docusaurus JSON, 그리고 (`features.translateSVG`, `translate-svg` 및 `svg` 블록을 통해) 독립형 SVG 자산에 대한 파이프라인도 제공합니다.
+
+<small>**다른 언어로 읽기:** </small>
+
+<small id="lang-list">[en-GB](../README.md) · [de](./README.de.md) · [es](./README.es.md) · [fr](./README.fr.md) · [hi](./README.hi.md) · [ja](./README.ja.md) · [ko](./README.ko.md) · [pt-BR](./README.pt-BR.md) · [zh-CN](./README.zh-CN.md) · [zh-TW](./README.zh-TW.md)</small>
+
+## 두 가지 핵심 워크플로우
+
+**워크플로우 1 - UI 번역** (React, Next.js, Node.js, 모든 i18next 프로젝트)
+
+소스 파일에서 `t("…")` 호출을 스캔하여 마스터 카탈로그(`strings.json` 및 선택적 로케일별 **`models`** 메타데이터 포함)를 구축하고, OpenRouter를 통해 로케일별로 누락된 항목을 번역하며, i18next에 바로 사용 가능한 평면 JSON 파일(`de.json`, `pt-BR.json`, …)을 작성합니다.
+
+**워크플로우 2 - 문서 번역** (마크다운, Docusaurus JSON)
+
+`documentations` 블록의 `contentPaths`에서 `.md` 및 `.mdx` 파일을, 해당 블록의 `jsonSource`에서 JSON 레이블 파일을 활성화 시 번역합니다. 블록별로 Docusaurus 스타일 또는 단순 로케일 접미사 형식 레이아웃을 지원합니다(`documentations[].markdownOutput`). 공유 루트 `cacheDir`에 SQLite 캐시를 저장하여 새로운 또는 변경된 세그먼트만 LLM으로 전송합니다. **SVG:** `features.translateSVG`를 활성화하고 최상위 `svg` 블록을 추가한 후 `translate-svg`를 사용하세요(둘 다 설정된 경우 `sync`에서도 실행됨).
+
+두 워크플로우는 동일한 `ai-i18n-tools.config.json` 파일을 공유하며 독립적으로 또는 함께 사용할 수 있습니다. 독립형 SVG 번역은 `features.translateSVG`와 최상위 `svg` 블록을 사용하며 `translate-svg`(또는 `sync` 내의 SVG 단계)를 통해 실행됩니다.
+
+---
+
+## 설치
+
+배포된 패키지는 **ESM 전용**입니다(`"type": "module`). Node.js, 번들러 또는 `import()`에서 `import`를 사용하세요 — **`require('ai-i18n-tools')`는 지원되지 않습니다.**
+
+```bash
+npm install ai-i18n-tools
+# or
+pnpm add ai-i18n-tools
+```
+
+OpenRouter API 키를 설정하세요:
+
+```bash
+export OPENROUTER_API_KEY=sk-or-v1-your-key-here
+```
+
+---
+
+## 빠른 시작
+
+### 워크플로우 1 - UI 문자열
+
+```bash
+# 1. Create config
+npx ai-i18n-tools init
+
+# 2. Extract t("…") calls from source
+npx ai-i18n-tools extract
+
+# 3. Translate to all target locales
+npx ai-i18n-tools translate-ui
+```
+
+`'ai-i18n-tools/runtime'`의 헬퍼를 사용하여 앱에 i18next를 연결하세요:
+
+```js
+import i18n from 'i18next';
+import { initReactI18next } from 'react-i18next';
+import uiLanguages from './locales/ui-languages.json';
+import {
+  defaultI18nInitOptions,
+  wrapI18nWithKeyTrim,
+  makeLoadLocale,
+  applyDirection,
+} from 'ai-i18n-tools/runtime';
+
+// Must match sourceLocale in ai-i18n-tools.config.json
+export const SOURCE_LOCALE = 'en-GB';
+
+void i18n.use(initReactI18next).init(defaultI18nInitOptions(SOURCE_LOCALE));
+wrapI18nWithKeyTrim(i18n);
+i18n.on('languageChanged', applyDirection);
+applyDirection(i18n.language);
+
+const localeLoaders = Object.fromEntries(
+  uiLanguages
+    .filter(({ code }) => code !== SOURCE_LOCALE)
+    .map(({ code }) => [code, () => import(`./locales/${code}.json`)])
+);
+export const loadLocale = makeLoadLocale(i18n, localeLoaders, SOURCE_LOCALE);
+export default i18n;
+```
+
+### 워크플로우 2 - 문서
+
+```bash
+# 1. Create config for Docusaurus
+npx ai-i18n-tools init -t ui-docusaurus
+
+# 2. Translate all docs
+npx ai-i18n-tools translate-docs
+
+# 3. Check status
+npx ai-i18n-tools status
+```
+
+### 두 워크플로우 모두
+
+```bash
+npx ai-i18n-tools sync   # Extract UI strings, then translate UI strings, SVG, and docs
+```
+
+---
+
+## 런타임 헬퍼
+
+`'ai-i18n-tools/runtime'`에서 내보내집니다 - 모든 JS 환경에서 작동하며, i18next 가져오기가 필요하지 않습니다:
+
+| 헬퍼 | 설명 |
+|---|---|
+| `defaultI18nInitOptions(sourceLocale)` | 키를 기본값으로 사용하는 설정을 위한 표준 i18next 초기화 옵션입니다. |
+| `wrapI18nWithKeyTrim(i18n)` | 키가 조회되기 전에 트리밍되도록 `i18n.t`를 래핑합니다. |
+| `makeLoadLocale(i18n, loaders, sourceLocale)` | 비동기 로케일 파일 로딩을 위한 팩토리 함수입니다. |
+| `getTextDirection(lng)` | BCP-47 코드에 대해 `'ltr'` 또는 `'rtl'`을 반환합니다. |
+| `applyDirection(lng, element?)` | `document.documentElement`에 `dir` 속성을 설정합니다. |
+| `getUILanguageLabel(lang, t)` | 언어 메뉴 행에 대한 표시 레이블입니다(i18n 사용). |
+| `getUILanguageLabelNative(lang)` | `t()`를 호출하지 않는 표시 레이블입니다(헤더 스타일). |
+| `interpolateTemplate(str, vars)` | 일반 문자열에 대한 `{{var}}` 치환을 위한 저수준 함수(내부적으로 사용됨; 앱 코드는 대신 `t()`를 사용해야 함). |
+| `flipUiArrowsForRtl(text, isRtl)` | RTL 레이아웃을 위해 `→`를 `←`로 뒤집습니다. |
+
+---
+
+## CLI 명령어
+
+```
+ai-i18n-tools init [-t ui-markdown|ui-docusaurus]   Create config file
+ai-i18n-tools extract                               Scan source for t("…") calls
+ai-i18n-tools translate-docs [--locale <code>]      Translate documentation (markdown, JSON); see docs for
+                                                    --force-update, --force, --stats, --clear-cache,
+                                                    --prompt-format (xml | json-array | json-object)
+ai-i18n-tools translate-svg [--locale <code>]       Standalone SVG assets (features.translateSVG + config.svg); see --no-cache
+ai-i18n-tools translate-ui [--locale <code>]        Translate UI strings only; see --force, --dry-run
+ai-i18n-tools export-ui-xliff [--locale <code>]     Export UI strings to XLIFF 2.0 (one file per locale); see --untranslated-only, -o
+ai-i18n-tools sync                                  Extract UI strings, then translate UI strings, SVG, and docs
+ai-i18n-tools status                                Translation status per file × locale
+ai-i18n-tools editor                                Open cache/glossary web editor
+ai-i18n-tools cleanup [--dry-run] [--no-backup] [--backup <path>]   Runs sync --force-update, then cleans stale + orphaned cache rows; backs up SQLite by default
+ai-i18n-tools glossary-generate                     Create empty glossary CSV template
+```
+
+모든 명령은 `-c <config>` (기본값: `ai-i18n-tools.config.json`), `-v` (자세한 정보), 및 선택적 `-w` / `--write-logs [path]`를 받아들이며, 콘솔 출력을 로그 파일에 추가합니다 (기본값: 번역 캐시 디렉토리 아래).
+
+---
+
+## 문서
+
+- [시작하기](docs/GETTING_STARTED.ko.md) - 두 워크플로우에 대한 전체 설정 가이드, 모든 CLI 플래그 및 구성 필드 참조.
+- [패키지 개요](docs/PACKAGE_OVERVIEW.ko.md) - 아키텍처, 내부 구조, 프로그래밍 API 및 확장 지점.
+- [AI 에이전트 컨텍스트](../docs/ai-i18n-tools-context.md) - 코드 또는 구성 변경을 하는 에이전트 및 유지 관리자를 위한 간결한 프로젝트 컨텍스트.
+
+---
+
+## 라이센스
+
+MIT © [Waldemar Scudeller Jr.](https://github.com/wsj-br)

package/translated-docs/README.pt-BR.md

@@ -0,0 +1,157 @@
+# ai-i18n-tools
+
+Kit de ferramentas CLI e programático para internacionalização de aplicações e sites de documentação em JavaScript/TypeScript. Extrai strings de interface, traduz com LLMs via OpenRouter e gera arquivos JSON prontos para uso em múltiplos idiomas para o i18next, além de pipelines para markdown, JSON do Docusaurus e (por meio de `features.translateSVG`, `translate-svg` e o bloco `svg`) ativos SVG autônomos.
+
+<small>**Leia em outros idiomas:** </small>
+
+<small id="lang-list">[en-GB](../README.md) · [de](./README.de.md) · [es](./README.es.md) · [fr](./README.fr.md) · [hi](./README.hi.md) · [ja](./README.ja.md) · [ko](./README.ko.md) · [pt-BR](./README.pt-BR.md) · [zh-CN](./README.zh-CN.md) · [zh-TW](./README.zh-TW.md)</small>
+
+## Dois fluxos de trabalho principais
+
+**Fluxo de Trabalho 1 - Tradução de UI** (React, Next.js, Node.js, qualquer projeto i18next)
+
+Escaneia arquivos fonte em busca de chamadas `t("…")`, constrói um catálogo mestre (`strings.json` com metadados **`models`** opcionais por localidade), traduz entradas ausentes por localidade via OpenRouter e escreve arquivos JSON planos (`de.json`, `pt-BR.json`, …) prontos para i18next.
+
+**Fluxo de Trabalho 2 - Tradução de Documentos** (Markdown, JSON do Docusaurus)
+
+Traduz arquivos `.md` e `.mdx` dos `contentPaths` de cada bloco `documentations` e arquivos JSON de rótulos da `jsonSource` desse bloco quando habilitado. Suporta layouts com sufixos de idioma no estilo Docusaurus e layouts planos por bloco (`documentations[].markdownOutput`). O `cacheDir` raiz compartilhado armazena o cache SQLite para que apenas segmentos novos ou alterados sejam enviados ao LLM. **SVG:** habilite `features.translateSVG`, adicione o bloco `svg` no nível superior e use `translate-svg` (também executado por `sync` quando ambos estiverem configurados).
+
+Ambos os fluxos de trabalho compartilham um único arquivo `ai-i18n-tools.config.json` e podem ser usados de forma independente ou em conjunto. A tradução autônoma de SVG usa `features.translateSVG` mais o bloco `svg` no nível superior e é executada por meio de `translate-svg` (ou pelo estágio SVG dentro de `sync`).
+
+---
+
+## Instalação
+
+O pacote publicado é **apenas ESM** (`"type": "module"`). Use `import` do Node.js, empacotadores ou `import()` — **`require('ai-i18n-tools')` não é suportado.**
+
+```bash
+npm install ai-i18n-tools
+# or
+pnpm add ai-i18n-tools
+```
+
+Defina sua chave de API do OpenRouter:
+
+```bash
+export OPENROUTER_API_KEY=sk-or-v1-your-key-here
+```
+
+---
+
+## Início rápido
+
+### Fluxo de Trabalho 1 - Strings da UI
+
+```bash
+# 1. Create config
+npx ai-i18n-tools init
+
+# 2. Extract t("…") calls from source
+npx ai-i18n-tools extract
+
+# 3. Translate to all target locales
+npx ai-i18n-tools translate-ui
+```
+
+Conecte i18next em seu aplicativo usando os auxiliares de `'ai-i18n-tools/runtime'`:
+
+```js
+import i18n from 'i18next';
+import { initReactI18next } from 'react-i18next';
+import uiLanguages from './locales/ui-languages.json';
+import {
+  defaultI18nInitOptions,
+  wrapI18nWithKeyTrim,
+  makeLoadLocale,
+  applyDirection,
+} from 'ai-i18n-tools/runtime';
+
+// Must match sourceLocale in ai-i18n-tools.config.json
+export const SOURCE_LOCALE = 'en-GB';
+
+void i18n.use(initReactI18next).init(defaultI18nInitOptions(SOURCE_LOCALE));
+wrapI18nWithKeyTrim(i18n);
+i18n.on('languageChanged', applyDirection);
+applyDirection(i18n.language);
+
+const localeLoaders = Object.fromEntries(
+  uiLanguages
+    .filter(({ code }) => code !== SOURCE_LOCALE)
+    .map(({ code }) => [code, () => import(`./locales/${code}.json`)])
+);
+export const loadLocale = makeLoadLocale(i18n, localeLoaders, SOURCE_LOCALE);
+export default i18n;
+```
+
+### Fluxo de Trabalho 2 - Documentação
+
+```bash
+# 1. Create config for Docusaurus
+npx ai-i18n-tools init -t ui-docusaurus
+
+# 2. Translate all docs
+npx ai-i18n-tools translate-docs
+
+# 3. Check status
+npx ai-i18n-tools status
+```
+
+### Ambos os fluxos de trabalho
+
+```bash
+npx ai-i18n-tools sync   # Extract UI strings, then translate UI strings, SVG, and docs
+```
+
+---
+
+## Auxiliares em tempo de execução
+
+Exportado de `'ai-i18n-tools/runtime'` - funciona em qualquer ambiente JS, sem necessidade de importação do i18next:
+
+| Auxiliar | Descrição |
+|---|---|
+| `defaultI18nInitOptions(sourceLocale)` | Opções padrão de inicialização do i18next para configurações de chave como padrão. |
+| `wrapI18nWithKeyTrim(i18n)` | Envolve `i18n.t` para que as chaves sejam cortadas antes da busca. |
+| `makeLoadLocale(i18n, loaders, sourceLocale)` | Fábrica para carregamento assíncrono de arquivos de localidade. |
+| `getTextDirection(lng)` | Retorna `'ltr'` ou `'rtl'` para um código BCP-47. |
+| `applyDirection(lng, element?)` | Define o atributo `dir` em `document.documentElement`. |
+| `getUILanguageLabel(lang, t)` | Rótulo exibido para uma linha de menu de idioma (com i18n). |
+| `getUILanguageLabelNative(lang)` | Rótulo exibido sem chamar `t()` (estilo cabeçalho). |
+| `interpolateTemplate(str, vars)` | Substituição de baixo nível `{{var}}` em uma string simples (usado internamente; o código do aplicativo deve usar `t()` em vez disso). |
+| `flipUiArrowsForRtl(text, isRtl)` | Inverte `→` para `←` para layouts RTL. |
+
+---
+
+## Comandos CLI
+
+```
+ai-i18n-tools init [-t ui-markdown|ui-docusaurus]   Create config file
+ai-i18n-tools extract                               Scan source for t("…") calls
+ai-i18n-tools translate-docs [--locale <code>]      Translate documentation (markdown, JSON); see docs for
+                                                    --force-update, --force, --stats, --clear-cache,
+                                                    --prompt-format (xml | json-array | json-object)
+ai-i18n-tools translate-svg [--locale <code>]       Standalone SVG assets (features.translateSVG + config.svg); see --no-cache
+ai-i18n-tools translate-ui [--locale <code>]        Translate UI strings only; see --force, --dry-run
+ai-i18n-tools export-ui-xliff [--locale <code>]     Export UI strings to XLIFF 2.0 (one file per locale); see --untranslated-only, -o
+ai-i18n-tools sync                                  Extract UI strings, then translate UI strings, SVG, and docs
+ai-i18n-tools status                                Translation status per file × locale
+ai-i18n-tools editor                                Open cache/glossary web editor
+ai-i18n-tools cleanup [--dry-run] [--no-backup] [--backup <path>]   Runs sync --force-update, then cleans stale + orphaned cache rows; backs up SQLite by default
+ai-i18n-tools glossary-generate                     Create empty glossary CSV template
+```
+
+Todos os comandos aceitam `-c <config>` (padrão: `ai-i18n-tools.config.json`), `-v` (verbose) e opcionalmente `-w` / `--write-logs [caminho]` para adicionar a saída do console a um arquivo de log (padrão: sob o diretório de cache de tradução).
+
+---
+
+## Documentação
+
+- [Introdução](docs/GETTING_STARTED.pt-BR.md) - guia completo de configuração para ambos os fluxos de trabalho, todas as flags da CLI e referência de campos de configuração.  
+- [Visão Geral do Pacote](docs/PACKAGE_OVERVIEW.pt-BR.md) - arquitetura, internos, API programática e pontos de extensão.  
+- [Contexto do Agente de IA](../docs/ai-i18n-tools-context.md) - contexto conciso do projeto para agentes e mantenedores que fazem alterações de código ou configuração.
+
+---
+
+## Licença
+
+MIT © [Waldemar Scudeller Jr.](https://github.com/wsj-br)

package/translated-docs/README.zh-CN.md

@@ -0,0 +1,157 @@
+# ai-i18n-tools
+
+用于国际化 JavaScript/TypeScript 应用程序和文档站点的 CLI 和编程工具包。通过 OpenRouter 使用 LLM 提取 UI 字符串并进行翻译，并为 i18next 生成适用于各个语言环境的 JSON 文件，同时提供用于 markdown、Docusaurus JSON 的管道，以及（通过 `features.translateSVG`、`translate-svg` 和 `svg` 块）独立 SVG 资源的处理功能。
+
+<small>**以其他语言阅读：**</small>
+
+<small id="lang-list">[en-GB](../README.md) · [de](./README.de.md) · [es](./README.es.md) · [fr](./README.fr.md) · [hi](./README.hi.md) · [ja](./README.ja.md) · [ko](./README.ko.md) · [pt-BR](./README.pt-BR.md) · [zh-CN](./README.zh-CN.md) · [zh-TW](./README.zh-TW.md)</small>
+
+## 两种核心工作流
+
+**工作流 1 - UI 翻译** (React, Next.js, Node.js, 任何 i18next 项目)
+
+扫描源文件中的 `t("…")` 调用，构建主目录（包含可选按语言区域划分的 **`models`** 元数据的 `strings.json`），通过 OpenRouter 为每个语言区域翻译缺失的条目，并生成可供 i18next 直接使用的扁平化 JSON 文件（`de.json`, `pt-BR.json`, …）。
+
+**工作流 2 - 文档翻译** (Markdown, Docusaurus JSON)
+
+启用后，会翻译每个 `documentations` 块中 `contentPaths` 下的 `.md` 和 `.mdx` 文件，以及该块 `jsonSource` 中的 JSON 标签文件。每个块支持 Docusaurus 风格和扁平化带区域设置后缀的布局（`documentations[].markdownOutput`）。共享的根目录 `cacheDir` 用于存放 SQLite 缓存，因此只有新增或更改过的片段才会被发送到 LLM。**SVG：** 启用 `features.translateSVG`，添加顶层 `svg` 块，然后使用 `translate-svg`（当两者都设置时，也会在 `sync` 中运行）。
+
+两种工作流共享同一个 `ai-i18n-tools.config.json` 文件，可以独立使用或结合使用。独立的 SVG 翻译使用 `features.translateSVG` 加上顶层 `svg` 块，并通过 `translate-svg`（或 `sync` 中的 SVG 阶段）运行。
+
+---
+
+## 安装
+
+发布的包是 **仅支持 ESM** 的（`"type": "module"`）。在 Node.js、打包工具或 `import()` 中使用 `import` — **不支持 `require('ai-i18n-tools')`。**
+
+```bash
+npm install ai-i18n-tools
+# or
+pnpm add ai-i18n-tools
+```
+
+设置您的 OpenRouter API 密钥：
+
+```bash
+export OPENROUTER_API_KEY=sk-or-v1-your-key-here
+```
+
+---
+
+## 快速开始
+
+### 工作流 1 - UI 字符串
+
+```bash
+# 1. Create config
+npx ai-i18n-tools init
+
+# 2. Extract t("…") calls from source
+npx ai-i18n-tools extract
+
+# 3. Translate to all target locales
+npx ai-i18n-tools translate-ui
+```
+
+使用 `'ai-i18n-tools/runtime'` 中的辅助函数在您的应用中配置 i18next：
+
+```js
+import i18n from 'i18next';
+import { initReactI18next } from 'react-i18next';
+import uiLanguages from './locales/ui-languages.json';
+import {
+  defaultI18nInitOptions,
+  wrapI18nWithKeyTrim,
+  makeLoadLocale,
+  applyDirection,
+} from 'ai-i18n-tools/runtime';
+
+// Must match sourceLocale in ai-i18n-tools.config.json
+export const SOURCE_LOCALE = 'en-GB';
+
+void i18n.use(initReactI18next).init(defaultI18nInitOptions(SOURCE_LOCALE));
+wrapI18nWithKeyTrim(i18n);
+i18n.on('languageChanged', applyDirection);
+applyDirection(i18n.language);
+
+const localeLoaders = Object.fromEntries(
+  uiLanguages
+    .filter(({ code }) => code !== SOURCE_LOCALE)
+    .map(({ code }) => [code, () => import(`./locales/${code}.json`)])
+);
+export const loadLocale = makeLoadLocale(i18n, localeLoaders, SOURCE_LOCALE);
+export default i18n;
+```
+
+### 工作流 2 - 文档
+
+```bash
+# 1. Create config for Docusaurus
+npx ai-i18n-tools init -t ui-docusaurus
+
+# 2. Translate all docs
+npx ai-i18n-tools translate-docs
+
+# 3. Check status
+npx ai-i18n-tools status
+```
+
+### 两种工作流
+
+```bash
+npx ai-i18n-tools sync   # Extract UI strings, then translate UI strings, SVG, and docs
+```
+
+---
+
+## 运行时辅助函数
+
+从 `'ai-i18n-tools/runtime'` 导出 - 适用于任何 JavaScript 环境，无需导入 i18next：
+
+| 辅助函数 | 描述 |
+|---|---|
+| `defaultI18nInitOptions(sourceLocale)` | 适用于以键作为默认值的标准 i18next 初始化选项。 |
+| `wrapI18nWithKeyTrim(i18n)` | 包装 `i18n.t`，使其在查找前对键进行修剪。 |
+| `makeLoadLocale(i18n, loaders, sourceLocale)` | 用于异步加载语言区域文件的工厂函数。 |
+| `getTextDirection(lng)` | 根据 BCP-47 代码返回 `'ltr'` 或 `'rtl'`。 |
+| `applyDirection(lng, element?)` | 在 `document.documentElement` 上设置 `dir` 属性。 |
+| `getUILanguageLabel(lang, t)` | 用于语言菜单行的显示标签（使用 i18n）。 |
+| `getUILanguageLabelNative(lang)` | 不调用 `t()` 的显示标签（标题样式）。 |
+| `interpolateTemplate(str, vars)` | 对纯字符串进行 `{{var}}` 替换的低级函数（内部使用；应用代码应使用 `t()`）。 |
+| `flipUiArrowsForRtl(text, isRtl)` | 为 RTL 布局翻转 `→` 为 `←`。 |
+
+---
+
+## CLI 命令
+
+```
+ai-i18n-tools init [-t ui-markdown|ui-docusaurus]   Create config file
+ai-i18n-tools extract                               Scan source for t("…") calls
+ai-i18n-tools translate-docs [--locale <code>]      Translate documentation (markdown, JSON); see docs for
+                                                    --force-update, --force, --stats, --clear-cache,
+                                                    --prompt-format (xml | json-array | json-object)
+ai-i18n-tools translate-svg [--locale <code>]       Standalone SVG assets (features.translateSVG + config.svg); see --no-cache
+ai-i18n-tools translate-ui [--locale <code>]        Translate UI strings only; see --force, --dry-run
+ai-i18n-tools export-ui-xliff [--locale <code>]     Export UI strings to XLIFF 2.0 (one file per locale); see --untranslated-only, -o
+ai-i18n-tools sync                                  Extract UI strings, then translate UI strings, SVG, and docs
+ai-i18n-tools status                                Translation status per file × locale
+ai-i18n-tools editor                                Open cache/glossary web editor
+ai-i18n-tools cleanup [--dry-run] [--no-backup] [--backup <path>]   Runs sync --force-update, then cleans stale + orphaned cache rows; backs up SQLite by default
+ai-i18n-tools glossary-generate                     Create empty glossary CSV template
+```
+
+所有命令都接受 `-c <config>`（默认值：`ai-i18n-tools.config.json`）、`-v`（详细模式）以及可选的 `-w` / `--write-logs [path]`，用于将控制台输出附加到日志文件（默认值：在翻译缓存目录下）。
+
+---
+
+## 文档
+
+- [入门指南](docs/GETTING_STARTED.zh-CN.md) - 包含两种工作流程的完整设置指南、所有 CLI 标志和配置字段参考。
+- [包概述](docs/PACKAGE_OVERVIEW.zh-CN.md) - 架构、内部结构、编程 API 和扩展点。
+- [AI 代理上下文](../docs/ai-i18n-tools-context.md) - 为进行代码或配置更改的代理和维护者提供简明的项目上下文。
+
+---
+
+## 许可证
+
+MIT © [Waldemar Scudeller Jr.](https://github.com/wsj-br)