ʻŌlelo Honua: AI JSON translation for JavaScript i18n

Generate and sync JSON locale files for JavaScript and Node.js projects using OpenRouter. Start with a source locale, choose target languages, and let an LLM draft translations while ʻŌlelo Honua preserves the JSON key structure.

Use the generated files with your existing i18n framework, including i18next. AI translations are drafts; have a fluent speaker review them before release.

Install from npm · View the source on GitHub

For a detailed look at how the translation, critique, and repair pipeline works, see docs/deep_dive.md.

Installation

npm install olelo-honua
# or
yarn add olelo-honua

Quick Start

const { OleloHonua } = require("olelo-honua");

const translator = new OleloHonua({
  provider: {
    platform: OleloHonua.Providers.OpenRouter,
    credentials: {
      apiKey: process.env.OPENROUTER_API_KEY,
    },
    modelId: OleloHonua.OpenRouterModels.NVIDIA.NEMOTRON_3_ULTRA_550B_FREE,
  },
  primeLanguage: "en",
  includeLanguage: ["haw", "es", "fr", "de", "zh", "ja", "ko", "ar", "ru"],
});

// Generate or sync all locale files
translator.hanaHou(); // alias: createLocaleFiles()

primeLanguage

The primeLanguage must have a corresponding locale file (e.g. locales/en.json) that serves as the source for all translations. All other languages are generated from it.

CLI

# Generate locale files from a config
npx olelo-honua init --config ./local.config.json

# Sync after updating your base locale file
npx olelo-honua sync

Configuration

API Key Setup

Store your API key in a .env file (add it to .gitignore):

OPENROUTER_API_KEY=<your_key>

Load it in your app:

require("dotenv").config();

• How to set up an OpenRouter API key

Full Configuration Example

{
  "primeLanguage": "en",
  "provider": {
    "platform": "OpenRouter",
    "credentials": {
      "apiKey": "<your_openrouter_api_key>"
    },
    "modelId": "nvidia/nemotron-3-ultra-550b-a55b:free"
  },
  "retries": {
    "mainLoop": 3,
    "critiqueLoop": 2,
    "repairLoop": 1
  },
  "debug": false,
  "includeLanguage": ["haw", "ar", "es", "fr"],
  "maxChunkRequests": 4,
  "additionalConfig": {
    "critique": true,
    "saveCritique": false,
    "repair": false,
    "multiLanguageAgreementThreshold": 0.8
  }
}

Providers and Models

Currently implemented: OpenRouter. OpenAI, Google Cloud Translation, and local LLM providers are not implemented yet.

OpenRouter Models

OpenRouter provides access to models from multiple providers through one API. The IDs below match the models exposed by OleloHonua.OpenRouterModels; :free models are free-tier listings. Availability, pricing, and rate limits can change, so check the OpenRouter model catalog before choosing a model.

Recent models

• Anthropic: anthropic/claude-fable-5.2, anthropic/claude-opus-5.5, anthropic/claude-sonnet-5.5, anthropic/claude-haiku-5.5
• DeepSeek: deepseek/deepseek-v4.1-flash-1017, deepseek/deepseek-v4.1-flash
• Google: google/gemini-4-argon, google/gemini-omni-1.2-flash, google/gemini-omni-1.1-flash, google/gemini-3.8-flash
• MiniMax: minimax/minimax-m3.1-flash
• Moonshot: moonshotai/kimi-k3.1-pro
• Mistral: mistralai/mistral-large-4-0
• NVIDIA: nvidia/nemotron-3.5-super-vl, nvidia/nemotron-3.5-lightning
• Qwen: qwen/qwen3.8-max-prime, qwen/qwen3.8-omni-flash, qwen/qwen3.8-flash
• xAI: x-ai/grok-4.7
• Z.ai: z-ai/glm-5.3-prime, z-ai/glm-5.3-flashx, z-ai/glm-5.3-flash

OpenAI Models

• Recent model IDs: openai/gpt-6.1-terra-pro, openai/gpt-6.1-terra, openai/gpt-6.1-sol-pro, openai/gpt-6.1-sol, openai/gpt-6-luna-pro, openai/gpt-6-luna
• Additional model IDs: openai/gpt-5.6-sol, openai/gpt-5.6-terra, openai/gpt-5.6-luna, openai/gpt-5.5, openai/gpt-5.4, openai/gpt-5.4-mini, openai/gpt-5, openai/gpt-5-mini, openai/gpt-4o, openai/gpt-4o-mini
• Legacy: openai/gpt-3.5-turbo, openai/gpt-4

These IDs are exposed by OleloHonua.OpenAIModels. The OpenAI provider is not currently implemented; use the OpenRouter provider for supported OpenRouter model IDs.

Free model listings may have rate limits. If you hit quota errors, reduce maxChunkRequests or switch to a paid model.

Caching

Completed translations are saved to .translations_cache.json to avoid redundant API calls on subsequent runs. To force a full retranslation:

rm .translations_cache.json

Use Cases

• Node.js apps: Call hanaHou() as part of a build step or deployment script to keep locale files in sync.
• Shopify: Automate translation of theme strings. See docs/shopify_integrations.md.
• Next.js: See docs/nextjs_integrations.md.
• Remix: See docs/remix_integrations.md.

Supported Languages

Includes Hawaiian and 80+ others:

Contributing

See docs/contributing.md.

Code of Conduct

See docs/code_of_conduct.md.

License

MIT