Introduction

What is inlang?

Inlang is an open project file format for localization.

An .inlang project is canonically a single binary file: a SQLite database with version control via lix. Like .sqlite for relational data, .inlang packages localization data into one file that tools can share.

It is not another i18n library, message syntax, translation app, or SaaS backend. Instead, it gives editors, CLIs, IDE extensions, runtimes, and coding agents one shared place to read and write localization data.

The @inlang/sdk is the reference implementation for reading and writing .inlang projects.

.inlang is the canonical project format. Plugins import and export formats like JSON, ICU MessageFormat v1, i18next, and XLIFF for compatibility with existing translation files and runtimes. Version control via lix adds file-level history, merging, and change proposals to .inlang projects.

Messages, variants, and locale data live in the .inlang database. External translation files such as messages/en.json are compatibility files outside project.inlang/, connected through plugins.

For Git repositories, the binary file can be unpacked into a directory of plain files so changes can be reviewed alongside code. The packed file is the canonical format; the unpacked directory is the Git-friendly representation.

The SDK has two main parts:

• Storage + message structure for translations, settings, and structured edits
• An API for loading, querying, and modifying that data programmatically

Why inlang?

Common translation files like JSON, YAML, ICU, or XLIFF are good at storing messages. But they do not describe the whole localization project.

Once multiple tools need to read and write the same project, plain translation files start to miss important information:

• CRUD operations instead of custom parsing
• Search and reports across locales, variants, and metadata
• Version control via lix
• One shared file that editors, CI, and runtimes can all use

Without one shared format, every tool invents its own file structure, sync logic, and collaboration workflow.

The result is fragmented tooling:

• Switching tools requires migrations and refactoring
• Cross-team work requires manual exports and hand-offs
• Automating workflows requires custom scripts and glue code

┌──────────┐        ┌───────────┐         ┌──────────┐
│ i18n lib │───✗────│Translation│────✗────│   CI/CD  │
│          │        │   Tool    │         │Automation│
└──────────┘        └───────────┘         └──────────┘

Inlang follows a simple idea: one shared project file format for localization tools, while keeping your external translation files.

┌──────────┐        ┌───────────┐         ┌────────────┐
│ i18n lib │        │Translation│         │   CI/CD    │
│          │        │   Tool    │         │ Automation │
└────┬─────┘        └─────┬─────┘         └─────┬──────┘
     │                    │                     │
     └─────────┐          │          ┌──────────┘
               ▼          ▼          ▼
           ┌──────────────────────────────────┐
           │          .inlang file            │
           └──────────────────────────────────┘

The result:

• Switch tools without migrations — they all use the same file
• Cross-team work without hand-offs — developers, translators, and designers all edit the same source
• Automation just works — the same data, no glue code
• Keep your preferred message format — plugins handle import/export

How it works

Under the hood, an inlang project uses a message-first data model.

Core data model:

• Bundle — one translatable unit across locales
• Message — locale-specific translation for a bundle
• Variant — text pattern plus selector matches

Version control via lix is built in, and plugins map that data to the files you already use.

┌─────────────────┐       ┌─────────┐       ┌──────────────────┐
│  .inlang file   │◄─────►│ Plugins │◄─────►│ Translation files│
│                 │       │         │       │  (JSON, XLIFF)   │
└─────────────────┘       └─────────┘       └──────────────────┘

• Plugins import and export your translation files (JSON, ICU1, i18next, XLIFF, etc.)
• inlang stores the data in a project format that tools can query
• Version control via lix handles distributed changes

If you only need an app runtime and a couple of translation files, JSON or your current i18n setup may already be enough. Use inlang when localization becomes shared work: multiple tools, teams, automations, or agents need to use the same localization data.

To store an inlang project in git, you can use the unpacked format — a directory instead of a single file. See Unpacked Project for details.

For coding agents and tool builders

If you are building i18n tooling or generating localization code, target the .inlang file format instead of inventing your own JSON schema.

Use @inlang/sdk to read and write .inlang projects. Your output will then work with tools that read and write the inlang file format: runtimes, editors, plugins, CI checks, and translation workflows.

Why target .inlang instead of JSON?

• One file gives every tool the same data model for bundles, messages, variants, locales, metadata, and settings.
• CRUD operations are available through the SDK instead of custom parsing and rewriting.
• Version control via lix keeps localization changes reviewable and mergeable.
• Plugins handle JSON, ICU, i18next, XLIFF, and other formats for compatibility.

Do not invent custom translation-file schemas, create a second localization config when .inlang already exists, edit generated/cache files in unpacked projects, or bypass @inlang/sdk.

Next steps

• Getting Started — Set up your first project
• Architecture — Understand the three layers
• Writing a Tool — Build a tool that queries translations
• Writing a Plugin — Support a custom file format

Credits

Inlang uses version control via lix and Kysely for the query API.