Show HN: Lin – CLI tool that uses LLMs to automate/manage internationalization

lin is a CLI tool that translates locale JSONs using LLMs

or use -g to install globally for non-npm projects.

You will need:

• a project with i18n set up
• a default locale JSON file (e.g. en-US.json)
• API keys for your chosen LLM providers in your .env file (e.g., OPENAI_API_KEY, ANTHROPIC_API_KEY)

See LLM Config.

lin will try to automatically detect your i18n configuration from your existing project setup. It supports:

• i18next (i18next-parser.config.js)
• Next.js (next.config.js)
• Nuxt.js (nuxt.config.js)
• Vue I18n (vue.config.js)
• Angular (angular.json)
• Svelte (svelte.config.js)
• Ember.js (ember-cli-build.js)
• Gatsby (gatsby-config.js)
• Solid.js (vite.config.js)
• Qwik (vite.config.js or package.json)
• Astro (astro.config.mjs or astro-i18next.config.mjs)
• Remix (package.json)

If your setup is not detected automatically, you can specify the integration using the integration config, and lin will only try to load the specified framework.

Or you can create a configuration file to tell lin about your i18n setup. You have two options:

1. Use lin.config.ts: Add an i18n object to your main lin.config.ts file.

   Example lin.config.ts:

   import { defineConfig } from '@yuo-app/lin' export default defineConfig({ i18n: { locales: ['en-US', 'es-ES'], defaultLocale: 'en-US', directory: 'locales', }, // ... other lin config })

2. Use i18n.config.ts: Or if you don't plan to use other lin config, just create a i18n.config.ts file.

   Example i18n.config.ts:

   import { defineI18nConfig } from '@yuo-app/lin' export default defineI18nConfig({ locales: ['en-US', 'es-ES'], defaultLocale: 'en-US', directory: 'locales', })

The main command is translate. It automates the entire process of finding new keys in your code, adding them to your default locale, and translating them into all other languages.

For it to work, you need to provide a default value when you use your translation function:

Then, just run:

lin will find header.title, add it to your default locale file with the value "Default value", and then translate it to all other locales.

Use the with option to manage the LLM's context.

To translate only specific locales, list them like this:

To also remove unused keys from all locales, use the --remove-unused flag:

To make the output more minimal (for CI or scripts), use the --silent flag:

You can use translate in GitHub Actions. lin will automatically find new keys, add them to your locales, and translate them on every push to main.

Here's an example workflow:

Don't forget to add your LLM provider API keys to your repo secrets.

While translate is the most end-to-end command, lin provides more granular commands for specific tasks:

• translate: check --fix + sync
• sync: Translates missing keys from your default locale to all other locales using LLMs.
• add: Adds a new key to your default locale and translates it to all other locales using LLMs.
• edit: Edit an existing key and its translations manually.
• del: Remove one or more keys.
• check: Validate locale files, check for missing/unused keys, or sort them. Quick config check.
• models: List available LLM models.
• undo: Revert the last change made by translate, sync, add, del, edit, or check.

The sync command syncs all locale JSON files with the default locale JSON file. It finds the missing keys in locales, and translates them.

To sync only specific locales, list them like this:

You can also use the sync command to add a new language.

1. First add the locale code to locales in the i18n config
2. Then run lin sync and it will create the new locale JSON file

add can be useful when writing a new part of the UI. You can use it to quickly add a new key to the default locale and translate it to all the other locales.

ui.button.save will be the key, and Text of the save button will be the value for the default locale. This will then be translated to all other locales.

To add a key to only specific locales, use the -l flag. You can repeat the flag for multiple locales.

This will add the key to es and fr locales (and the default locale).

edit can be used to quickly edit an existing key in the default locale and all the other locales.

This is a niche command, but maybe useful for quickly editing a specific key without having to search for it, or for LLM agents if you don't want to feed the entire locale json file, or have them edit the files themselves.

To edit a key in only specific locales, use the -l flag.

del removes keys from the locale JSON files.

The check command is a versatile tool for validating and maintaining locale files. It's ideal for running in pre-commit hooks or in CI.

By default, it lints your codebase for missing and unused translation keys by comparing your source files against the default locale.

To get a minimal output, use the --silent or -S flag. This is recommended for CI and git hooks. See check with git hooks.

This will report any discrepancies. To add the missing keys to your default locale file with empty strings instead of throwing an error, use the --fix flag:

To remove unused keys from all locale files, use the --remove-unused flag.

You can also use check to find missing keys in your locales compared to the default locale file with the --keys flag (this skips the codebase parsing):

This will report any discrepancies. If you want to automatically add the missing keys with empty strings, use the --fix flag:

You can also use check to sort your locale JSON files, either alphabetically or based on the key order in your default locale file.

To display detailed info about your config and locales, use the --info flag:

A great way to enforce i18n consistency is to run lin check automatically before each commit. You can use simple-git-hooks with lint-staged to set this up easily.

Add this to your package.json:

Then run:

You can also run lin check -S -f or lin check -S -r to automatically fix issues, or even lin translate -S to translate them too.

undo reverts the last changes made by translate, sync, add, del, edit, or check.

To see a list of all available LLM providers and models:

• Run lin -M, lin --models or lin models to list all models.
• To filter by provider, just specify providers after the command: lin -M openai google

lin automatically saves a backup of any files modified by the add, del, check, and translate commands. You can disable this feature with the --no-undo flag, or by setting undo: false in your config file.

lin uses unconfig to find and load your configuration files. You can use one of the following:

• lin.config.ts (or .js, .mjs, etc.)
• .linrc (or with extension, or .json)
• lin property in package.json If you are not using one of the auto-detected frameworks, you can put your i18n config inside your lin config, or create a separate i18n.config.ts file.

See src/config/i18n.ts for a full list of configuration sources.

for the add and sync commands

lin uses the Vercel AI SDK to support multiple LLM providers. The currently supported providers are:

• openai
• anthropic
• google
• xai
• mistral
• groq
• azure

You need to specify the model and the provider in your configuration or via the --model (-m) and --provider (-p) CLI flags.

Make sure the corresponding API key is set in your env variables (e.g., OPENAI_API_KEY, ANTHROPIC_API_KEY).

Example lin.config.ts with LLM options:

All options under options are passed to the Vercel AI SDK.

To save LLM options, you can define and name different model configurations in your lin.config.ts file.

You can then activate a preset using the --model flag. Any other CLI flags will override the preset's values.

This simple string is directly added to the system prompt. Use it to provide extra information to the LLM about your project.

The batchSize option controls how many target locale files are sent to the LLM for translation in a single request. This can be useful for projects with many languages.

You can set this in your lin.config.ts using batchSize or use the --batchSize (or -b) flag in the CLI. The CLI flag will always override the config file setting.

The with option allows you to control which locale files are included in the LLM's context window. This can significantly improve translation quality by providing the model with more context about your project's wording and style.

You can set this in your lin.config.ts using with or use the --with (or -w) flag in the CLI. The CLI flag will always override the config file setting.

Context Profiles:

• none (default): Only the keys to be translated are sent to the LLM. This is the most cost-effective option.
• def: Includes the entire default locale JSON file (e.g., en-US.json) in the context.
• tgt: Includes the full JSON of each locale currently being translated.
• both: Includes both the default locale file and the target locale files.
• all: Includes every locale JSON file in the context. This may be expensive.
• <locale>: You can also provide one or more specific locale codes (e.g., es-ES, fr).

Examples: