{"slug": "ai-translation-stack", "title": "AI-Translation-Stack", "summary": "A new open-source project called AI-Translation-Stack provides a framework-independent catalog engine for AI-assisted JSON translation, with a next-intl adapter for Next.js runtime messages. The stack layers catalog core, source-state tracking, message safety, glossary, exact and semantic memory, context extraction, source scanning, provenance, and provider adapters, and requires Node.js 22.17 or newer plus TypeScript 7's native compiler for its checked-in typecheck command. Commands including audit, sync, baseline, scan, test, lint, and build make no provider request, and an API key is required only for the translate command.", "body_md": "| Layer | Responsibility | \n|---|---|\n| Catalog core | Load, validate, audit, baseline, synchronize, and atomically checkpoint JSON catalogs. | \n| Source-state tracking | Detect changed English/source values and invalidate stale locale values. | \n| Message safety | Preserve placeholders and HTML tag names/counts across translation. | \n| Glossary | Validate curated entries, build provider context, reject forbidden terms, and learn high-confidence proposals. | \n| Exact memory | Reuse approved translations only when their identity is still valid. | \n| Semantic memory | Store packed float32 vectors, reconcile orphaned entries, and rank similar examples by cosine similarity. | \n| Context extraction | Heuristically infer UI role, screen, sibling keys, and length budgets from TypeScript/JS call sites. | \n| Source scanner | Detect likely hard-coded user-facing strings and enforce a reviewed baseline ratchet. | \n| Provenance | Record locale, model, requested/accepted/omitted keys, response id, errors, and usage without storing prompt text. | \n| Provider adapter | Translate JSON objects and optionally create embeddings through provider-specific APIs. | \n| Next integration | Supply merged messages to `next-intl` with a configurable locale fallback policy. | \n| CLI and CI | Run the checks locally and in GitHub Actions without requiring a provider secret. | \n\n```\nsource catalog (en.json)\n        │\n        ├── source snapshot ── stale-source invalidation\n        │\n        ├── catalog audit/sync ── locale catalogs ({locale}.json)\n        │\n        └── translation runner\n              ├── context extraction\n              ├── exact translation memory lookup\n              ├── optional semantic example retrieval\n              ├── glossary-aware provider request\n              ├── structural + terminology validation\n              ├── atomic per-chunk catalog checkpoint\n              ├── exact memory and optional vector checkpoint\n              ├── glossary learning (high-confidence only)\n              └── provenance batch record\n\nnext-intl adapter ── source catalog + non-empty locale values ── merged runtime messages\n```\n\nThe core is intentionally independent of a web framework. It reads and writes catalogs through explicit paths, and it accepts provider implementations through `TranslationProvider`. The `next-intl` integration is an adapter, not a requirement of the catalog engine.\n\n- Node.js 22.17 or newer\n- npm with lockfile support\n- TypeScript 7 native compiler is used by the checked-in typecheck command\n- An API key is required only for `translate`\n- A catalog directory and a JSON configuration file\n\nNo provider request is made by `audit`, `sync`, `baseline`, `scan`, `test`, `lint`, or `build`.\n\n```\ngit clone https://github.com/<owner>/ai-translation-stack.git\ncd ai-translation-stack\nnpm ci\nnpm run build\nnpm test\n```\n\nThe repository contains newly authored fixtures under `examples/`. Establish the source snapshot before auditing or translating those fixtures:\n\n```\nnode dist/cli.js baseline --config examples/translation.config.json\nnode dist/cli.js audit --config examples/translation.config.json\nnode dist/cli.js scan --config examples/translation.config.json --write-baseline --check\n```\n\nThe same command surface is available through the npm scripts. For example:\n\n```\nnpm run catalog:baseline -- --config examples/translation.config.json\nnpm run catalog:audit -- --config examples/translation.config.json\nnpm run source:scan -- --config examples/translation.config.json --check\n```\n\n`sync` copies missing and empty source values into locale catalogs, invalidates values whose source changed, preserves non-empty translations, and preserves locale-only keys:\n\n```\nnode dist/cli.js sync --config examples/translation.config.json\nnode dist/cli.js sync --config examples/translation.config.json --dry-run\n```\n\nCopy `.env.example` to your own environment configuration or export the variables through your shell. Do not commit the resulting file.\n\n```\n# Select one provider. The CLI flag --provider overrides this variable.\n$env:TRANSLATION_PROVIDER = 'deepseek'\n$env:DEEPSEEK_API_KEY = Read-Host 'DeepSeek API key'\n$env:TRANSLATION_MODEL = 'deepseek-v4-flash'\n\n# Translate only one locale first\nnode dist/cli.js translate --provider deepseek --config examples/translation.config.json --locale de --verbose\n```\n\nThe supported provider identifiers are `openai`, `claude`, `deepseek`, `glm`, `grok`, and `gemini`. The equivalent environment variables are listed in `.env.example`; only the credential for the selected provider is required. Provider-specific model defaults are used when `TRANSLATION_MODEL` is empty.\n\nSupported runner options:\n\n| Option | Effect | \n|---|---|\n| `--config <path>` | Load a typed JSON configuration from this path. | \n| `--locale <code>` | Process one configured target locale. | \n| `--full` | Re-request eligible values instead of using incremental selection. | \n| `--dry-run` | Call the provider and report validation without writing catalog or sidecar files. | \n| `--no-memory` | Skip exact and semantic memory reuse for this run. | \n| `--verbose` | Report rejected keys and chunk outcomes without printing source text or secrets. | \n\nThe runner checkpoints after each chunk. A failed chunk is recorded in provenance and the next chunk/locale can continue. A retry of a successful chunk replaces the same memory identity rather than appending an unbounded duplicate.\n\nThe core depends on this interface:\n\n```\nexport interface TranslationProvider {\n  readonly name: string\n  readonly model: string\n  translate(request: TranslationRequest): Promise<TranslationResponse>\n  embed?(texts: readonly string[]): Promise<readonly (readonly number[])[]>\n}\n```\n\nThe package includes six selectable provider adapters:\n\n| Provider | Selector | Credential | Default model | Transport | Semantic embeddings | \n|---|---|---|---|---|---|\n| OpenAI | `openai` | `OPENAI_API_KEY` | `gpt-5.6-luna` | OpenAI-compatible chat and embeddings | Enabled | \n| Claude | `claude` | `ANTHROPIC_API_KEY` | `claude-sonnet-4-5-20250929` | Native Messages API | Not assumed | \n| DeepSeek | `deepseek` | `DEEPSEEK_API_KEY` | `deepseek-v4-flash` | OpenAI-compatible chat | Not assumed | \n| GLM | `glm` | `GLM_API_KEY` (or`ZAI_API_KEY` ) | `glm-4.6` | Z.AI OpenAI-compatible chat | Not assumed | \n| Grok | `grok` | `XAI_API_KEY` | `grok-4.6` | xAI OpenAI-compatible chat | Not assumed | \n| Gemini | `gemini` | `GEMINI_API_KEY` | `gemini-3.8-flash` | Native Gemini Interactions API | Not assumed | \n\nUse `--provider <name>` for a single run or `TRANSLATION_PROVIDER=<name>` for the default CLI selection. `TRANSLATION_MODEL`, `TRANSLATION_BASE_URL`, timeout, and completion-token settings are shared overrides; provider-specific base URL variables are available for private gateways and regional endpoints. Claude uses its native request field for the output limit, while the GPT-5-compatible path uses `max_completion_tokens`.\n\nThe OpenAI-compatible adapters share bounded fetch retries, JSON extraction, glossary proposal parsing, usage mapping, and response validation. DeepSeek enables JSON mode; GLM and Grok rely on the strict JSON prompt plus tolerant parser because their compatible endpoints can differ by deployment. Claude extracts only text content blocks and deliberately does not advertise an embedding method. Gemini uses the native Interactions API with a JSON response format, maps `model_output` text steps and native usage fields, opts out of server-side storage with `store: false`, and deliberately does not advertise an embedding method. When a provider has no embedding method, exact translation memory, glossary checks, structural validation, checkpoints, and provenance continue to work; only semantic retrieval is skipped.\n\nReview each provider's current documentation and data controls before sending a catalog: [Claude Messages](https://platform.claude.com/docs/en/api/messages-examples), [DeepSeek JSON output](https://api-docs.deepseek.com/guides/json_mode/), [Z.AI OpenAI-compatible setup](https://docs.z.ai/guides/develop/openai/python), [xAI chat completions](https://docs.x.ai/developers/model-capabilities/legacy/chat-completions), [Gemini Interactions API](https://ai.google.dev/api/interactions-api), and [Gemini REST quickstart](https://ai.google.dev/tutorials/rest_quickstart). Source strings can contain business logic, personal data, or confidential product language; the stack does not classify or redact them for you.\n\n`translation.config.json` is the source of truth for locale and storage policy. The included template shows the full target-locale shape used by the original stack without shipping its catalogs or translated values. The `examples/translation.config.json` file is intentionally smaller so CI remains deterministic and data-free.\n\nImportant fields:\n\n```\n{\n  \"sourceLocale\": \"en\",\n  \"locales\": [{ \"code\": \"de\", \"name\": \"German\", \"nativeName\": \"Deutsch\" }],\n  \"messagesDir\": \"messages\",\n  \"sourceSnapshotFile\": \".en-source-snapshot.json\",\n  \"translationMemoryFile\": \".translation-memory.json\",\n  \"semanticMemoryFile\": \".semantic-memory.json\",\n  \"confirmedSameFile\": \".confirmed-same.json\",\n  \"glossaryFile\": \"translation-glossary.json\",\n  \"provenanceFile\": \".provenance.json\",\n  \"chunkSize\": 100\n}\n```\n\nPaths are resolved relative to the configuration file. The source catalog is `<messagesDir>/<sourceLocale>.json`; target catalogs are `<messagesDir>/<locale>.json`. Target locale codes are derived from `locales`, so the CLI and runtime adapter do not maintain a second hand-copied language list.\n\n- Source values must be strings.\n- Empty and missing target values are pending and fall back to the source value at runtime.\n- Non-empty target translations are preserved by `sync` .\n- Extra target keys are reported rather than silently deleted.\n- Changed source values are reset to the source value before they become eligible for retranslation.\n- Removed source keys are not automatically deleted from target catalogs; review them as a deliberate cleanup.\n- The source snapshot must be created intentionally with `baseline` and should be reviewed like any other generated state.\n\nInstall `next-intl` in the host application and create a request configuration that uses the adapter:\n\n``` js\n// i18n/request.ts\nimport { createNextIntlRequestConfig } from 'ai-translation-stack/next-intl'\nimport { loadTranslationConfig } from 'ai-translation-stack'\n\nconst config = loadTranslationConfig('./translation.config.json')\n\nexport default createNextIntlRequestConfig({ config })\n```\n\nThe adapter:\n\n1. awaits the requested locale;\n2. accepts only the source locale or a configured target locale;\n3. falls back to the source locale for an unknown value;\n4. loads the source catalog first;\n5. overlays only non-empty string translations; and\n6. returns one merged message object for the framework.\n\nKeep authentication, route negotiation, cookies, country detection, analytics, authorization, and application navigation in the host application. They do not belong in this reusable adapter.\n\nThe blocking local gate is:\n\n```\nnpm run format:check\nnpm run typecheck\nnpm run lint\nnpm test\nnpm run build\nnpm run catalog:audit -- --config examples/translation.config.json\nnpm run source:scan -- --config examples/translation.config.json --check\nnpm run secret:scan\nnpm run package:check\n```\n\nGitHub Actions runs the same categories on Node.js 22.17. The tests use temporary directories and mocked providers; they never insert state directly into an external database and never require a network credential.\n\nThe source scanner is intentionally heuristic. It is a review ratchet, not an AST proof that every string is localized. Treat additions as a code-review decision and keep the baseline small and current.\n\n```\nsrc/\n  adapters/next-intl.ts       optional runtime integration\n  cli.ts                      command-line entry point\n  config.ts                   typed configuration loader\n  core/\n    atomic-json.ts            atomic JSON/binary persistence with retries\n    catalog.ts                audit, baseline, and synchronization\n    context.ts                usage-context extraction\n    message-structure.ts      placeholder/tag validation\n    provenance.ts             provider-run provenance\n    semantic-memory.ts        packed-vector semantic memory\n    source-scan.ts            hard-coded-string scanner\n    source-state.ts           source snapshot and stale invalidation\n    translation-glossary.ts   glossary validation and learning\n    translation-memory.ts     exact translation memory\n    types.ts                  public contracts\n  providers/claude.ts        native Claude Messages adapter\n  providers/deepseek.ts      DeepSeek-compatible adapter\n  providers/factory.ts       CLI/environment provider selection\n  providers/glm.ts           GLM-compatible adapter\n  providers/grok.ts          Grok-compatible adapter\n  providers/http.ts          bounded fetch transport and retries\n  providers/openai.ts        backward-compatible OpenAI adapter\n  providers/openai-compatible.ts shared compatible transport\n  providers/shared.ts        prompts, JSON, glossary, and usage normalization\n  translate.ts                chunked translation orchestrator\nexamples/\n  messages/                   small, newly authored catalog fixtures\n  source/                     small, newly authored call-site fixture\n  translation.config.json    deterministic CI configuration\nscripts/\n  lint.mjs                    dependency-free static lint entry point\n  secret-scan.mjs             repository secret scan\n```\n\nRuntime sidecars are intentionally not part of the public source fixture. They contain project-specific translations, provider metadata, or embeddings when generated and are ignored by default.\n\nUse this stack when a project has JSON message catalogs, incremental translation runs, repeated terminology, or a framework runtime that must fall back safely when a locale is incomplete.\n\nIt is not a complete content-management system, a human translation agency, a secrets manager, a privacy classifier, or a guarantee that an AI translation is linguistically correct. Human review remains appropriate for legal, medical, financial, safety-critical, and brand-sensitive language.\n\nSee [CONTRIBUTING.md](/antonihabek/AI-translation-stack/blob/main/CONTRIBUTING.md) for development setup and pull-request expectations. Keep provider calls behind mocks in tests, do not add real customer catalogs, and include a regression test for every changed safety rule.\n\nSee [SECURITY.md](/antonihabek/AI-translation-stack/blob/main/SECURITY.md). Never commit `.env` files, API keys, provider responses, translation-memory entries from confidential work, embeddings, or provenance that exposes sensitive source text. Atomic persistence protects a file checkpoint from partial writes; it does not make the surrounding filesystem or provider trustworthy.\n\nAI Translation Stack is distributed under the [Apache License, Version 2.0](/antonihabek/AI-translation-stack/blob/main/LICENSE). See [NOTICE](/antonihabek/AI-translation-stack/blob/main/NOTICE) for project attribution and trademark clarification. The Apache License is a permissive software license; this repository is not operated by or affiliated with the Apache Software Foundation.", "url": "https://wpnews.pro/news/ai-translation-stack", "canonical_source": "https://github.com/antonihabek/AI-translation-stack", "published_at": "2026-09-10 09:01:23+00:00", "updated_at": "2026-09-10 09:24:28.074357+00:00", "lang": "en", "topics": ["ai-tools", "developer-tools", "natural-language-processing", "ai-products"], "entities": ["AI-Translation-Stack", "Node.js 22.17", "TypeScript 7", "next-intl", "GitHub Actions", "TranslationProvider"], "alternates": {"html": "https://wpnews.pro/news/ai-translation-stack", "markdown": "https://wpnews.pro/news/ai-translation-stack.md", "text": "https://wpnews.pro/news/ai-translation-stack.txt", "jsonld": "https://wpnews.pro/news/ai-translation-stack.jsonld"}}