Skip to content

CLI — Models & languages ​

check-models ​

Synopsis: ai-i18n-tools check-models

Validate each configured model id against the active provider's GET /models list (membership and expiration_date). Requires that provider's API key (none for keyless providers like Ollama). Exits non-zero when any configured id is missing or expired, and respects the resolved request timeout (requestTimeout or requestTimeoutMs on the provider, otherwise the top-level value). When the provider returns pricing (e.g. OpenRouter), also shows USD per 1M tokens for prompt/completion. When providers.cheaperinference.zeroDataRetention is true, the check uses GET /v1/models?zdr=true and fails an id that catalog leaves out.

See also: AI Models, LLM providers


list-models ​

Synopsis: ai-i18n-tools list-models

List every model the active provider advertises via its GET /models list (sorted by id; active provider follows the config provider key, override with -P / --provider). Requires that provider's API key (none for keyless providers like Ollama). When the provider returns pricing (e.g. OpenRouter), also shows USD per 1M tokens for prompt/completion, and tags entries past expiration_date. When providers.cheaperinference.zeroDataRetention is true, the list is GET /v1/models?zdr=true.

Key options: -P / --provider

See also: AI Models, LLM providers


suggest-models ​

Synopsis: ai-i18n-tools suggest-models [--quality | --price] [--top <n>] [--json] [--apply] [--list] [--max-price <usd>] [--min-delta <points>] [--refresh]

Rank the active provider's chat models and print the top ones (default 8). The table columns, in order, are rank, model id, index (quality score times 100, one decimal), measured languagebench ChrF, measured Arena Score, input price, output price, blended price in USD per 1M tokens, and frontier tier. A missing measurement is —. The command needs that provider's API key (none for keyless providers such as Ollama). The active provider follows config provider; override it with -P / --provider.

Candidates come from the provider's GET /models list. When providers.cheaperinference.zeroDataRetention is true, that request is GET /v1/models?zdr=true. Expired rows and non-chat rows (embeddings, speech, image, video, moderation, rerankers) are left out. If that catalog request fails, the command exits 1.

The index is quality only: languagebench ChrF and Arena Score. Price is not part of the index. --quality is the default. It sorts by index, then by cheaper blended price when two models show the same index. --price lists the quality-price Pareto frontier cheapest first. A model is dominated when another model costs no more and has at least the same index, and is strictly cheaper or strictly higher on the index. An exact tie on blended price and index shares the tier. Non-dominated models are tier 1, then tier 2, and so on. The tier is that depth, not the distance from the best index. Models with no price, then models below the quality floor, follow the frontier. Passing both flags is an error. Passing neither means quality. Optional modelSuggestion weights in config replace either profile's ChrF/Arena mix and quality floor. See Configuration. The same ranking is used by the dashboard Models tab.

ChrF is the mean of languagebench translation_from and translation_to rows whose metric is chrf, limited to this project's sourceLocale and targetLocales. Locales map to a languagebench language code (the primary subtag, with a few aliases such as pt-BR to pt and zh-Hant to zh and yue). An empty set uses en. Arena is the LMArena overall Arena Score, not Elo.

The blended price is (3 × input + output) / 4 USD per 1M tokens. Its source is resolved in this order: a non-zero catalog rate, then models.dev input and output rates, then languagebench's single cost figure. A catalog price of 0 is unpriced, not free. An unknown price does not change the index. On --quality it sorts last among equal indices. On --price an unpriced model that clears the floor comes after every frontier tier.

A missing ChrF sorts below the quality floor. The placeholder values 0.35 and 0.45 used when ChrF or Arena is missing affect only the index; the table prints — instead. The frontier column is 1 for an undominated priced model that clears the floor, 2 for the next tier, and — when the model has no price, is below the floor, or is an alias. Two ids that share ChrF, Arena Score, input price, and output price are aliases. The shorter id is kept, and an id with no date in it wins over a dated one (preview-06-05, 20241022). Alias rows stay in the full ranking and are left out of the table, --json, and --apply. --list still shows them. When the printed rows include a dominated model, a line under the table names the tier 1 model that beats it.

--quality puts models that clear the floor first, then higher index, then a cheaper blended price. --top (default 8, an integer of at least 1) limits the table, the --json fragment, and --apply together, after the filters below.

--list prints the same columns for the active provider's configured translationModels, in that order, and ignores --top. The rank column is still each model's place in the full ranking. A configured id that is missing from the catalog, expired, or not a chat model is still listed, with — for measurements. --list cannot be combined with --apply.

Alias rows are removed first, except with --list. --max-price then keeps models whose blended price per 1M tokens is less than or equal to that many USD. A model with no blended price is left out. --min-delta then walks the remaining rows and keeps a model only when its index differs from the previous kept model by at least that many points. The first remaining model is always kept. A delta of 0 does not drop rows. Rows with no index are left out when the delta is greater than 0. Rank numbers stay the ones from the full list. With --list, the walk follows translationModels order and keeps aliases. Both filters also apply to --json and --apply. For a quality list that will be applied, --max-price keeps a fallback inside a budget and --min-delta drops a small index step. A dominated row under the cap can remain; the frontier column and the line under the table show it. The Models tab has the same two controls and also omits aliases.

--json writes this object to stdout (paste it inside the provider block) and sends the table and the attribution footer to stderr:

json
{
  "translationModels": ["model-a", "model-b"]
}

--apply copies the current config to a sibling ai-i18n-tools.config.{timestamp}.backup.json (or {name}.{timestamp}.backup.json when -c names another file), then replaces providers.<active>.translationModels with those ids. A name collision adds -2, -3, and so on before .backup.json. If the copy fails, the config file is left unchanged. uiModels and localeModels are left unchanged. Scores are not written into the config file. The dashboard Update config button writes the same backup.

Benchmark data is cached at <cacheDir>/benchmark-scores.json (usually .translation-cache/benchmark-scores.json) for seven days. The raw datasets are downloaded at runtime and are not shipped in the package. --refresh redownloads languagebench, Arena, and models.dev. A source that fails during --refresh is not filled from the previous cache. Without --refresh, a failed download reuses the cached slice. If one of languagebench or Arena fails, the command ranks with the other and says which source failed. If both fail, it exits 1. A models.dev failure leaves catalog prices in place. The dashboard has no refresh control; run --refresh from the CLI, then reload the Models tab.

The footer attributes languagebench (CC BY-SA 4.0), the LMArena Arena Score (CC BY 4.0), and models.dev (MIT).

Key options: --quality, --price, --top, --json, --apply, --list, --max-price, --min-delta, --refresh, -P / --provider

See also: AI Models, Models tab


bench-models ​

Synopsis: ai-i18n-tools bench-models [--model <ids>] [--text <text> | --file <path>] [--source <locale>] [--target <locale>]

Benchmark each configured model by translating one sample in isolation (single-model client, no fallback chain). Prints a table of model id, input/output tokens, wall-clock translation time, and USD cost (— for providers that do not report cost), plus a totals row and per-model failures.

Models default to the union of the active provider's translationModels, uiModels, and localeModels ids (override with --model); the sample defaults to a built-in English markdown block (override with --text / --file); source/target default to config sourceLocale and the first docs[] target locale, falling back to the top-level targetLocales (override with --source / --target). Runs models in parallel, bounded by config concurrency (default 4); each model is still timed individually. Requires the active provider's API key.

Key options: --model, --text, --file, --source, --target

See also: AI Models


list-languages ​

Synopsis: ai-i18n-tools list-languages [search]

List the bundled UI languages catalog (data/ui-languages-complete.json) as a human-readable table (code, text direction, English name, native name). Needs no config or API key. Pass an optional search term to keep only entries whose code, native name, English name, or direction contain it (case-insensitive), e.g. list-languages portuguese, list-languages rtl, list-languages zh.

Released under the MIT License.