@inlang/sdk NPM

Inlang file format SDK

Outline

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.

Core Features

📁 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.

Installation

npm install @inlang/sdk

Loading an inlang file

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

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

// query the project
project.*

Next steps

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.

Available Plugins

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

Creating a Plugin

Getting started

Implement the InlangPlugin type.

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

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.

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.

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

API reference

Creating a new project

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);

Loading a project

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

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

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

Querying a project

// 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);

Querying changes

!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.

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

Saving a project

const newFile = await project.toBlob();

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

Importing and exporting translation files

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.

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);

Installing plugins

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)

Unpacked inlang files (directories)

!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.

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

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

// modify the project

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