Getting Started with l10n.dev

l10n.dev is an AI-powered localization platform built for developers and localization teams. It translates your i18n files while preserving keys, structure, placeholders, and plural forms — from your AI agent, your terminal, your CI pipeline, or the web workspace. This page walks you through your first translation and shows what the platform can do once you are set up.

Step 1: Create an Account

Create Your API Key

Everything outside the web workspace — the AI agent, the CLI, the GitHub Action, the plugins, and the API — authenticates with an API key. Create one on the API Keys page and keep it somewhere safe: you will paste it into your agent config, your CLI config, or your CI secrets. You can revoke and re-issue a key at any time.

Step 2: Pick How You Want to Localize

There are three ways to use l10n.dev. They share the same translation engine, character balance, glossaries, and linguistic instructions — so pick the one that fits your workflow today, and mix them later.

AI Localization Agent (MCP)

Connecting your AI agent to our MCP server turns it into a professional localization tool. Instead of translating strings itself — burning context and drifting between runs — the agent calls l10n.dev as a dedicated translation engine and gets a finished file back. It's like having a localization expert on your team.

• Token-efficient: translated content never passes through your agent's context window, so your coding assistant keeps working on code.
• Format guarantees: keys, ordering, placeholders, and plural forms come back intact — no broken JSON to clean up afterwards.
• Persistent memory: glossaries and linguistic instructions are stored on our side, so quality does not depend on what the agent happens to remember.

Setup is a single command — here it is for Claude Code (Cursor, Windsurf, Copilot, Claude Desktop, and Codex are covered in the guide):

claude mcp add --env L10N_API_KEY=your-api-key-here --transport stdio l10n -- npx -y ai-l10n-mcp

Then simply ask your agent: "Translate src/i18n/en into German and Japanese." It will detect your project structure, translate, and write the files for you.

Read the AI Localization Agent guide

CLI & GitHub Actions

The ai-l10n npm package brings localization into your terminal and your CI/CD pipeline. Translate a file by hand while developing, then move the exact same command into a workflow so new strings are localized before they ever reach a reviewer.

• Project-structure detection: point it at your source file and it finds your existing target locales automatically.
• Incremental by default: with translateOnlyNewStrings only added or changed strings are sent and billed.
• Pipeline-ready: works the same locally, in GitHub Actions, GitLab CI, or Jenkins.

Install the package, store your API key, and translate your first file:

npm install ai-l10n

npx ai-l10n config --api-key YOUR_API_KEY

# Auto-detects target languages from your project structure
npx ai-l10n translate ./locales/en.json --update

# Or name them explicitly
npx ai-l10n translate ./locales/en.json --languages es,fr,de --update

To translate on every push, add our GitHub Action to your workflow:

name: Auto-translate i18n files

on:
  push:
    branches: [main]
    paths: ['locales/en/**']

permissions:
  contents: write

jobs:
  translate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: l10n-dev/ai-l10n@v1
        with:
          api-key: ${{ secrets.L10N_API_KEY }}
          config-file: 'ai-l10n.config.json'
          pull-request: false

Read the Localization Automation guide

Web Workspace

The workspace is the fastest way to see what the service produces — no API key, no installation. It is also where you manage your files, glossaries, instructions, and balance.

1. Upload your i18n file — JSON, YAML, PO, XLIFF, ARB, Markdown, or plain text.
2. Choose the source language and one or more target languages.
3. Optionally attach a glossary and linguistic instructions, and enable translating only new strings.
4. Press Translate, watch the progress, then download the result or copy it straight into your repository.

Open the workspace

Step 3: Tune the Translation Quality

Out of the box the AI already sees the surrounding keys and file structure as context. These two features let you lock in the vocabulary and the voice of your product, and they apply to every path above — agent, CLI, workspace, and API alike.

AI-Powered Glossary

A glossary pins down how your product names, feature names, and domain terms must be translated. Enable glossary generation and l10n.dev builds one automatically from your source and translated content, saving it as the active glossary for that language pair — so every future translation stays on-brand and consistent. You can also import your own glossary or generate one with AI.

Manage glossaries

Linguistic Instructions

Linguistic instructions tell the AI how to write: formal or casual, which form of address to use, how to handle brand names, product-specific conventions, or anything else that defines your voice. Write them once and they are applied to every translation for that language.

Manage linguistic instructions

Rule of thumb: use a glossary for what a word must become, and linguistic instructions for how the whole text should sound.

What Else You Get

Incremental Translation

We track your source strings by content, so re-running a translation only sends what actually changed. Existing, reviewed translations stay untouched, your Git diffs stay small, and you are only billed for the new text. We don't store your content; it's only hashed to detect changes, so your source strings remain private.

165 Languages and Every Common Format

Translate into 165 languages, including less commonly supported ones where human translators are hard to find. JSON, YAML, PO, XLIFF, ARB, Markdown, plain text, and OpenAPI specifications are all handled natively — including ICU messages and full CLDR plural forms.

Format Guarantee and Multiple LLMs

Every result is validated against the source: if a placeholder, a key, or the structure is lost, the chunk is retried automatically. Large files are split into chunks that keep their context, and we operate several LLMs so each language and content type gets the model that handles it best.

Integrations for Your Whole Team

Localization is not only a developer task. Bring l10n.dev into the tools your team already uses — plugins for Figma, Obsidian, a VS Code extension, the NPM package, MCP, and a documented REST API.

Browse all integrations

Your Privacy Matters

We don't store your translation data. When you do translate files in the workspace, you keep complete control over them — delete them at any time.

Manage your files

Dedicated Instance

If your organization needs isolated infrastructure, your own database and storage, your own model deployments, or custom compliance guarantees, we can run l10n.dev as a dedicated instance for you.

Read about dedicated instances

Free Tier and Packages

Every account gets 10,000 free characters every month. No charges, no credit card required — that is enough to localize a small app or to properly evaluate the quality before you commit.

If you need more than the free monthly quota, you can buy a package to increase your character balance. Use the email address associated with the order to sign in and access your benefits.

Available packages:

• 100K Characters
  Price: $4.90
  Translate 100,000 characters.*
• 1M Characters
  Price: $14.90
  Translate 1,000,000 characters.*
• 5M Characters
  Price: $39.90
  Translate 5,000,000 characters.*

*Each package is valid for 90 days, and the unused balance carries over when you buy again before it expires.

Compare all packages and pricing

Where to Go Next

Pick the next step that matches how you plan to work — or just translate a file and see the result for yourself.

Why Choose l10n.dev?

l10n.dev combines the power of AI with user-friendly tools to streamline your localization process. Whether you're a developer or part of a localization team, our platform ensures accurate, efficient, and affordable translations tailored to your needs.