Inlang file format SDK

 

Outline

- Introduction
- Getting Started
- Plugins
- API reference
- Listing on inlang.com

Introduction

The inlang SDK is the official specification and parser for .inlang files.

.inlang files are designed to become the open standard for i18n and enable interoperability between i18n solutions. Such solutions involve apps like Fink, libraries like Paraglide JS, or plugins that extend inlang.

$3

- 📁 File-based: Interoperability without cloud integrations or lock-in.
- 🖊️ CRUD API: Query messages with SQL.
- 🧩 Plugin System: Extend the capabilities with plugins.
- 📦 Import/Export: Import and export messages in different file formats.
- Change control: Collaboration, change proposals, reviews, and automation.

Getting Started

> [!Note]
> Inlang files can be unpacked and stored as directories. The long-term goal is to have portable .inlang files. Hence, the documentation refers to files instead of directories.

$3

``bash
npm install @inlang/sdk
`

$3

`ts
import { loadProjectInMemory, newProject } from "@inlang/sdk";

const project = await loadProjectInMemory({
blob: await newProject()
});

// query the project
project.*
`

$3

Go to the API reference to learn how to query messages, changes, and save the project.

Plugins

The inlang SDK supports plugins to extend its functionality.

Plugins can be used to import/export messages in different formats, add custom validation rules, and implement specialized workflows.

$3

Find available plugins on https://inlang.com/c/plugins.

$3

#### Getting started

Implement the InlangPlugin type.

Examples can be found here. Particulary the message format plugin is a good starting point.

`typescript
const myPlugin: InlangPlugin = {
key: "my-plugin",
importFiles: () => {
// Import files logic
},
exportFiles: () => {
// Export files logic
},
};
`

#### Deploying a plugin

> [!NOTE]
> Why is a CDN requires instead of using npm to use plugins?
>
> Non-JS projects (Android, iOS, etc.) wouldn't be able to use inlang, and browser-based apps like Fink couldn't load plugins.

`bash
npx @inlang/cli plugin build --entry ./src/plugin.js
`

We recommend uploading the plugin to NPM which makes it automatically available on JSDelivr and enables users to pin the version of your plugin.

`diff
https://cdn.jsdelivr.net/npm/my-plugin@1/dist/index.js
`

API reference

$3

`typescript
import { newProject } from "@inlang/sdk";

// Create a new project
const file = await newProject();

// write the file anywhere you want
await fs.writeFile("./project.inlang", file);
`

$3

`typescript
import { loadProjectInMemory } from "@inlang/sdk";

const file = await fs.readFile("./project.inlang");

// Load a project from a directory
const project = await loadProjectInMemory({
blob: file
});
`

$3

`typescript
// Accessing settings and plugins
const settings = await project.settings.get();
const plugins = await project.plugins.get();

// Querying messages
const messages = await project.db
.selectFrom("message")
.selectAll()
.execute();

console.log(messages);
`

$3

> [!NOTE]
> The inlang plugin for lix is work in progress. If you stumble on issues, please open an issue on the GitHub.

The inlang file format uses lix for change control. The lix APIs are exposed via project.lix.*. Visit the lix documentation for more information on how to query changes.

`typescript
const changes = await project.lix.db
.selectFrom("change")
.selectAll()
.execute();
`

$3

`typescript
const newFile = await project.toBlob();

await fs.writeFile("./project.inlang", newFile);
`

$3

The import and export of messages depends on the installed plugins. The following example shows how to import and export messages using a plugin that supports JSON files.

`typescript
const file = await fs.readFile("./en.json");

// Import files
await project.importFiles({
pluginKey: "plugin.inlang.messageFormat",
files: [
{ locale: "en", content: file },
],
});

// Export files
const files = await project.exportFiles({
pluginKey: "plugin.inlang.messageFormat"
});

await fs.writeFile("./en.json", files[0].content);
`

$3

`typescript
const settings = await project.settings.get();

settings.modules.push(
"https://cdn.jsdelivr.net/npm/@inlang/plugin-i18next@latest/dist/index.js"
)

await project.settings.set(settings)
`

$3

> [!NOTE]
> Unpacked inlang files are a workaround to store inlang files in git.
>
> Git can't handle binary files. If you don't intend to store the inlang file in git, do not use unpacked inlang files.
>
> Unpacked inlang files are not portable. They depent on plugins that and do not persist lix change control data.

`typescript
import {
loadProjectFromDirectory,
saveProjectToDirectory
} from "@inlang/sdk";

const project = await loadProjectFromDirectory({
"path": "./project.inlang"
});

// modify the project

await saveProjectToDirectory({
"project": project,
"path": "./project.inlang"
});
`

Listing on inlang.com

To list your app/plugin on inlang.com, please open a pull request to the registry.json file.

Make sure that the link you are contributing points to a marketplace-manifest.json` file. An example of can be found here