ai-i18n-tools 1.0.0

package/translated-docs/README.de.md

@@ -0,0 +1,157 @@
+# ai-i18n-tools
+
+CLI- und programmatisches Toolkit zur Internationalisierung von JavaScript/TypeScript-Anwendungen und Dokumentationsseiten. Extrahiert UI-Texte, übersetzt sie mithilfe von LLMs über OpenRouter und generiert sprachenspezifische JSON-Dateien für i18next sowie Pipelines für Markdown, Docusaurus-JSON und (über `features.translateSVG`, `translate-svg` und den `svg`-Block) eigenständige SVG-Ressourcen.
+
+<small>**In anderen Sprachen lesen:** </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>
+
+## Zwei Kernarbeitsabläufe
+
+**Arbeitsablauf 1 - UI-Übersetzung** (React, Next.js, Node.js, jedes i18next-Projekt)
+
+Durchsucht Quell-Dateien nach `t("…")`-Aufrufen, erstellt einen Master-Katalog (`strings.json` mit optionalen **`models`**-Metadaten pro Locale), übersetzt fehlende Einträge pro Locale über OpenRouter und schreibt flache JSON-Dateien (`de.json`, `pt-BR.json`, …), die für i18next bereit sind.
+
+**Arbeitsablauf 2 - Dokumentenübersetzung** (Markdown, Docusaurus JSON)
+
+Übersetzt `.md`- und `.mdx`-Dateien aus den `contentPaths` jedes `documentations`-Blocks sowie JSON-Beschriftungsdateien aus dem `jsonSource` dieses Blocks, wenn aktiviert. Unterstützt Docusaurus-artige und flache, sprachcodesuffixierte Layouts pro Block (`documentations[].markdownOutput`). Ein gemeinsames Stammverzeichnis `cacheDir` enthält den SQLite-Cache, sodass nur neue oder geänderte Segmente an das LLM gesendet werden. **SVG:** Aktivieren Sie `features.translateSVG`, fügen Sie den `svg`-Block auf oberster Ebene hinzu und verwenden Sie anschließend `translate-svg` (wird auch über `sync` ausgeführt, wenn beide aktiviert sind).
+
+Beide Workflows teilen sich eine einzige `ai-i18n-tools.config.json`-Datei und können unabhängig oder zusammen verwendet werden. Die eigenständige SVG-Übersetzung nutzt `features.translateSVG` zusammen mit dem `svg`-Block auf oberster Ebene und wird über `translate-svg` ausgeführt (oder über die SVG-Phase innerhalb von `sync`).
+
+---
+
+## Installation
+
+Das veröffentlichte Paket ist **ESM-only** (`"type": "module"`). Verwende `import` aus Node.js, Bundlern oder `import()` — **`require('ai-i18n-tools')` wird nicht unterstützt.**
+
+```bash
+npm install ai-i18n-tools
+# or
+pnpm add ai-i18n-tools
+```
+
+Setze deinen OpenRouter API-Schlüssel:
+
+```bash
+export OPENROUTER_API_KEY=sk-or-v1-your-key-here
+```
+
+---
+
+## Schnellstart
+
+### Arbeitsablauf 1 - UI-Strings
+
+```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
+```
+
+Integriere i18next in deiner App mithilfe der Helfer aus `'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;
+```
+
+### Arbeitsablauf 2 - Dokumentation
+
+```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
+```
+
+### Beide Arbeitsabläufe
+
+```bash
+npx ai-i18n-tools sync   # Extract UI strings, then translate UI strings, SVG, and docs
+```
+
+---
+
+## Laufzeit-Helfer
+
+Exportiert aus `'ai-i18n-tools/runtime'` - funktioniert in jeder JS-Umgebung, kein i18next-Import erforderlich:
+
+| Helfer | Beschreibung |
+|---|---|
+| `defaultI18nInitOptions(sourceLocale)` | Standard-i18next-Init-Optionen für Key-as-Default-Setups. |
+| `wrapI18nWithKeyTrim(i18n)` | Wickelt `i18n.t` so, dass Schlüssel vor der Suche getrimmt werden. |
+| `makeLoadLocale(i18n, loaders, sourceLocale)` | Fabrik für das asynchrone Laden von Locale-Dateien. |
+| `getTextDirection(lng)` | Gibt `'ltr'` oder `'rtl'` für einen BCP-47-Code zurück. |
+| `applyDirection(lng, element?)` | Setzt das `dir`-Attribut auf `document.documentElement`. |
+| `getUILanguageLabel(lang, t)` | Anzeige-Label für eine Sprachmenüzeile (mit i18n). |
+| `getUILanguageLabelNative(lang)` | Anzeige-Label ohne Aufruf von `t()` (Header-Stil). |
+| `interpolateTemplate(str, vars)` | Niedrigstufige `{{var}}`-Substitution auf einem einfachen String (intern verwendet; Anwendungs-Code sollte stattdessen `t()` verwenden). |
+| `flipUiArrowsForRtl(text, isRtl)` | Dreht `→` zu `←` für RTL-Layouts. |
+
+---
+
+## CLI-Befehle
+
+```
+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
+```
+
+Alle Befehle akzeptieren `-c <config>` (Standard: `ai-i18n-tools.config.json`), `-v` (ausführlich) und optional `-w` / `--write-logs [path]`, um die Konsolenausgabe in eine Protokolldatei anzuhängen (Standard: im Verzeichnis des Übersetzungscaches).
+
+---
+
+## Dokumentation
+
+- [Erste Schritte](docs/GETTING_STARTED.de.md) - vollständige Einrichtungsanleitung für beide Workflows, alle CLI-Flags und Referenz der Konfigurationsfelder.
+- [Paketübersicht](docs/PACKAGE_OVERVIEW.de.md) - Architektur, interne Abläufe, programmgesteuerte API und Erweiterungspunkte.
+- [AI-Agent-Kontext](../docs/ai-i18n-tools-context.md) - prägnanter Projektkontext für Agenten und Wartende, die Code- oder Konfigurationsänderungen vornehmen.
+
+---
+
+## Lizenz
+
+MIT © [Waldemar Scudeller Jr.](https://github.com/wsj-br)

package/translated-docs/README.es.md

@@ -0,0 +1,157 @@
+# herramientas-ai-i18n
+
+Kit de herramientas CLI y programático para internacionalizar aplicaciones y sitios de documentación en JavaScript/TypeScript. Extrae cadenas de interfaz de usuario, las traduce con modelos de lenguaje grande (LLM) a través de OpenRouter y genera archivos JSON listos para cada idioma para i18next, además de pipelines para markdown, JSON de Docusaurus y (mediante `features.translateSVG`, `translate-svg` y el bloque `svg`) activos SVG independientes.
+
+<small>**Leer en otros 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>
+
+## Dos flujos de trabajo principales
+
+**Flujo de trabajo 1 - Traducción de UI** (React, Next.js, Node.js, cualquier proyecto i18next)
+
+Escanea archivos fuente en busca de llamadas `t("…")`, construye un catálogo maestro (`strings.json` con metadatos **`models`** opcionales por localidad), traduce entradas faltantes por localidad a través de OpenRouter y escribe archivos JSON planos (`de.json`, `pt-BR.json`, …) listos para i18next.
+
+**Flujo de trabajo 2 - Traducción de documentos** (Markdown, JSON de Docusaurus)
+
+Traduce archivos `.md` y `.mdx` desde los `contentPaths` de cada bloque `documentations` y archivos JSON de etiquetas desde el `jsonSource` de ese bloque cuando está habilitado. Admite diseños con sufijo de idioma estilo Docusaurus y planos por bloque (`documentations[].markdownOutput`). El `cacheDir` raíz compartido contiene la caché SQLite para que solo se envíen al LLM segmentos nuevos o modificados. **SVG:** habilite `features.translateSVG`, agregue el bloque `svg` de nivel superior, luego use `translate-svg` (también se ejecuta desde `sync` cuando ambos están configurados).
+
+Ambos flujos de trabajo comparten un único archivo `ai-i18n-tools.config.json` y pueden usarse de forma independiente o conjunta. La traducción independiente de SVG utiliza `features.translateSVG` junto con el bloque `svg` de nivel superior y se ejecuta mediante `translate-svg` (o la etapa SVG dentro de `sync`).
+
+---
+
+## Instalación
+
+El paquete publicado es **solo ESM** (`"type": "module"`). Usa `import` desde Node.js, empaquetadores o `import()` — **`require('ai-i18n-tools')` no es compatible.**
+
+```bash
+npm install ai-i18n-tools
+# or
+pnpm add ai-i18n-tools
+```
+
+Establece tu clave API de OpenRouter:
+
+```bash
+export OPENROUTER_API_KEY=sk-or-v1-your-key-here
+```
+
+---
+
+## Inicio rápido
+
+### Flujo de trabajo 1 - Cadenas de 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
+```
+
+Conecta i18next en tu aplicación utilizando los ayudantes 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;
+```
+
+### Flujo de trabajo 2 - Documentación
+
+```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 flujos de trabajo
+
+```bash
+npx ai-i18n-tools sync   # Extract UI strings, then translate UI strings, SVG, and docs
+```
+
+---
+
+## Ayudantes de tiempo de ejecución
+
+Exportados de `'ai-i18n-tools/runtime'` - funcionan en cualquier entorno JS, no se requiere importación de i18next:
+
+| Ayudante | Descripción |
+|---|---|
+| `defaultI18nInitOptions(sourceLocale)` | Opciones de inicialización estándar de i18next para configuraciones de clave como predeterminadas. |
+| `wrapI18nWithKeyTrim(i18n)` | Envuelve `i18n.t` para que las claves se recorten antes de la búsqueda. |
+| `makeLoadLocale(i18n, loaders, sourceLocale)` | Fábrica para la carga asíncrona de archivos de localidad. |
+| `getTextDirection(lng)` | Devuelve `'ltr'` o `'rtl'` para un código BCP-47. |
+| `applyDirection(lng, element?)` | Establece el atributo `dir` en `document.documentElement`. |
+| `getUILanguageLabel(lang, t)` | Etiqueta de visualización para una fila de menú de idioma (con i18n). |
+| `getUILanguageLabelNative(lang)` | Etiqueta de visualización sin llamar a `t()` (estilo encabezado). |
+| `interpolateTemplate(str, vars)` | Sustitución de bajo nivel `{{var}}` en una cadena simple (usado internamente; el código de la aplicación debe usar `t()` en su lugar). |
+| `flipUiArrowsForRtl(text, isRtl)` | Invierte `→` a `←` para diseños RTL. |
+
+---
+
+## Comandos de 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 los comandos aceptan `-c <config>` (predeterminado: `ai-i18n-tools.config.json`), `-v` (detallado), y opcionalmente `-w` / `--write-logs [ruta]` para añadir la salida de la consola a un archivo de registro (predeterminado: en el directorio de caché de traducción).
+
+---
+
+## Documentación
+
+- [Introducción](docs/GETTING_STARTED.es.md) - guía completa de configuración para ambos flujos de trabajo, todas las banderas de CLI y referencia de campos de configuración.
+- [Descripción del Paquete](docs/PACKAGE_OVERVIEW.es.md) - arquitectura, internos, API programática y puntos de extensión.
+- [Contexto del Agente de IA](../docs/ai-i18n-tools-context.md) - contexto conciso del proyecto para agentes y mantenedores que realizan cambios en el código o la configuración.
+
+---
+
+## Licencia
+
+MIT © [Waldemar Scudeller Jr.](https://github.com/wsj-br)

package/translated-docs/README.fr.md

@@ -0,0 +1,157 @@
+# ai-i18n-tools
+
+Outil en ligne de commande et programme pour l'internationalisation d'applications JavaScript/TypeScript et de sites de documentation. Extrait les chaînes d'interface utilisateur, les traduit à l'aide de modèles linguistiques (LLM) via OpenRouter, puis génère des fichiers JSON prêts pour les paramètres régionaux destinés à i18next, ainsi que des pipelines pour le markdown, le JSON Docusaurus et (via `features.translateSVG`, `translate-svg` et le bloc `svg`) des ressources SVG autonomes.
+
+<small>**Lire dans d'autres langues :** </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>
+
+## Deux flux de travail principaux
+
+**Flux de travail 1 - Traduction de l'UI** (React, Next.js, Node.js, tout projet i18next)
+
+Analyse les fichiers source pour les appels `t("…")`, construit un catalogue maître (`strings.json` avec des métadonnées **`models`** optionnelles par locale), traduit les entrées manquantes par locale via OpenRouter, et écrit des fichiers JSON plats (`de.json`, `pt-BR.json`, …) prêts pour i18next.
+
+**Flux de travail 2 - Traduction de documents** (Markdown, Docusaurus JSON)
+
+Traduit les fichiers `.md` et `.mdx` à partir des `contentPaths` de chaque bloc `documentations` et les fichiers JSON d'étiquettes à partir du `jsonSource` de ce bloc lorsque cette fonction est activée. Prend en charge les structures de dossiers localisés au style Docusaurus ou plates, par bloc (`documentations[].markdownOutput`). Le `cacheDir` racine partagé contient le cache SQLite afin que seuls les segments nouveaux ou modifiés soient envoyés au LLM. **SVG :** activez `features.translateSVG`, ajoutez le bloc `svg` au niveau supérieur, puis utilisez `translate-svg` (également exécuté depuis `sync` lorsque les deux sont configurés).
+
+Les deux flux de travail partagent un seul fichier `ai-i18n-tools.config.json` et peuvent être utilisés indépendamment ou conjointement. La traduction SVG autonome utilise `features.translateSVG` ainsi que le bloc `svg` au niveau supérieur et s'exécute via `translate-svg` (ou l'étape SVG à l'intérieur de `sync`).
+
+---
+
+## Installation
+
+Le package publié est **uniquement ESM** (`"type": "module"`). Utilisez `import` depuis Node.js, des bundlers, ou `import()` — **`require('ai-i18n-tools')` n'est pas pris en charge.**
+
+```bash
+npm install ai-i18n-tools
+# or
+pnpm add ai-i18n-tools
+```
+
+Définissez votre clé API OpenRouter :
+
+```bash
+export OPENROUTER_API_KEY=sk-or-v1-your-key-here
+```
+
+---
+
+## Démarrage rapide
+
+### Flux de travail 1 - Chaînes 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
+```
+
+Connectez i18next dans votre application en utilisant les helpers 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;
+```
+
+### Flux de travail 2 - Documentation
+
+```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
+```
+
+### Les deux flux de travail
+
+```bash
+npx ai-i18n-tools sync   # Extract UI strings, then translate UI strings, SVG, and docs
+```
+
+---
+
+## Helpers d'exécution
+
+Exportés de `'ai-i18n-tools/runtime'` - fonctionnent dans n'importe quel environnement JS, aucune importation i18next requise :
+
+| Helper | Description |
+|---|---|
+| `defaultI18nInitOptions(sourceLocale)` | Options d'initialisation standard i18next pour les configurations clé-comme-par-défaut. |
+| `wrapI18nWithKeyTrim(i18n)` | Enveloppe `i18n.t` afin que les clés soient tronquées avant la recherche. |
+| `makeLoadLocale(i18n, loaders, sourceLocale)` | Fabrique pour le chargement asynchrone de fichiers de locale. |
+| `getTextDirection(lng)` | Renvoie `'ltr'` ou `'rtl'` pour un code BCP-47. |
+| `applyDirection(lng, element?)` | Définit l'attribut `dir` sur `document.documentElement`. |
+| `getUILanguageLabel(lang, t)` | Étiquette d'affichage pour une ligne de menu de langue (avec i18n). |
+| `getUILanguageLabelNative(lang)` | Étiquette d'affichage sans appeler `t()` (style en-tête). |
+| `interpolateTemplate(str, vars)` | Substitution de bas niveau `{{var}}` sur une chaîne simple (utilisé en interne ; le code de l'application doit utiliser `t()` à la place). |
+| `flipUiArrowsForRtl(text, isRtl)` | Retourne `→` à `←` pour les mises en page RTL. |
+
+---
+
+## Commandes 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
+```
+
+Toutes les commandes acceptent `-c <config>` (par défaut : `ai-i18n-tools.config.json`), `-v` (verbose), et l'optionnel `-w` / `--write-logs [path]` pour ajouter la sortie de la console à un fichier journal (par défaut : sous le répertoire de cache de traduction).
+
+---
+
+## Documentation
+
+- [Commencer](docs/GETTING_STARTED.fr.md) - guide complet de configuration pour les deux flux de travail, tous les drapeaux CLI et référence des champs de configuration.
+- [Aperçu du package](docs/PACKAGE_OVERVIEW.fr.md) - architecture, internes, API programmatique et points d'extension.
+- [Contexte de l'agent IA](../docs/ai-i18n-tools-context.md) - contexte de projet concis pour les agents et les mainteneurs effectuant des modifications de code ou de configuration.
+
+---
+
+## Licence
+
+MIT © [Waldemar Scudeller Jr.](https://github.com/wsj-br)

package/translated-docs/README.hi.md

@@ -0,0 +1,157 @@
+# ai-i18n-tools
+
+JavaScript/TypeScript अनुप्रयोगों और दस्तावेज़ीकरण साइटों के लिए अंतरराष्ट्रीयकरण के लिए CLI और प्रोग्रामेटिक टूलकिट। UI स्ट्रिंग्स निकालता है, OpenRouter के माध्यम से LLMs के साथ उनका अनुवाद करता है, और i18next के लिए भाषा-तैयार JSON फ़ाइलें उत्पन्न करता है, साथ ही मार्कडाउन, डॉक्यूसॉरस 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 - दस्तावेज़ अनुवाद** (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.hi.md) - दोनों कार्यप्रवाहों के लिए पूर्ण सेटअप गाइड, सभी CLI फ्लैग, और कॉन्फ़िग फ़ील्ड संदर्भ।
+- [पैकेज अवलोकन](docs/PACKAGE_OVERVIEW.hi.md) - आर्किटेक्चर, आंतरिक, प्रोग्रामेटिक API, और एक्सटेंशन पॉइंट्स।
+- [AI एजेंट संदर्भ](../docs/ai-i18n-tools-context.md) - एजेंटों और रखरखाव करने वालों के लिए संक्षिप्त परियोजना संदर्भ जो कोड या कॉन्फ़िग परिवर्तन कर रहे हैं।
+
+---
+
+## लाइसेंस
+
+MIT © [वाल्डेमर स्कुडेलर जूनियर](https://github.com/wsj-br)