Quick start

Get Langnostic up and running in your project in just a few minutes.

Prerequisites

• Node.js 18 or higher
• A project with source locale files in JSON or Markdown/MDX format

Installation

Install Langnostic in your project:

npm install langnostic @langnostic/plugin-json --save-dev

Ignore the .langnostic directory

Add the .langnostic directory into your .gitignore file. This directory is used for any intermediate data or debug output.

.langnostic

Initialize configuration

Initialize a default configuration file.

npx langnostic init

This creates a langnostic.config.ts file in the root of the project:

import { openai } from '@ai-sdk/openai';
import JsonPlugin from '@langnostic/plugin-json';
import type { ConfigType } from 'langnostic';

export default {
  ai: {
    model: openai('gpt-5'),
  },
  groups: [
    {
      name: 'app-strings',
      paths: [
        {
          source: './src/locales/en-US.json',
          target: './src/locales/{locale}.json',
        },
      ],
      plugin: JsonPlugin(),
    },
  ],
  localeConfig: {
    source: 'en-US',
    target: ['zh-CN', 'es-ES', 'fr-FR'],
  },
} satisfies ConfigType;

Configure the localization groups

Update the groups configuration to match your project structure.

For example, given a project with the following structure,

├── src
│   └── locales
│       └── en-US.json
├── package.json
└── langnostic.config.ts

Create a group that targets the source locale file at src/locales/en-US.json:

import { openai } from '@ai-sdk/openai';
import JsonPlugin from '@langnostic/plugin-json';
import type { ConfigType } from 'langnostic';

export default {
  ai: {
    model: openai('gpt-5'), // Other providers
  },
  localeConfig: {
    source: 'en-US',      // Your source locale
    target: ['zh-CN', 'pt-BR'],     // Locales to translate to
  },
  groups: [
    {
      name: 'app-strings',
      plugin: JsonPlugin(),
      paths: [
        {
          source: './src/locales/en-US.json',     // Path to source file
          target: './src/locales/{locale}.json',  // {locale} will be replaced with the target locales
        },
      ],
    },
  ],
} satisfies ConfigType;

After translating, two new files zh-CN.json and pt-BR.json will be created:

├── src
│   └── locales
│       ├── en-US.json
│       ├── pt-BR.json
│       └── zh-CN.json
├── package.json
└── langnostic.config.ts

Set up your AI provider

Langnostic uses AI models to translate content. Under the hood, it uses the AI SDK, which provides a common interface to access the major AI model providers and their latest models. AI SDK supports a huge list of AI Providers and it's always growing.

This allows you to have complete freedom over choice of AI model to use for the translation. You may change it anytime you want, without having to re-translate the entire project.

The default config uses the OpenAI provider via @ai-sdk/openai. Install that package, or others if you want to use a different model:

npm install @ai-sdk/openai --save-dev

Initialize the AI provider instance and pass it to the ai.model field of langnostic.config.ts:

import { openai } from '@ai-sdk/openai';

export default {
  ai: {
    model: openai('gpt-5'),
  },
  // Other options omitted...
};

Depending on your AI provider of choice, add the respective environment variable key and value to your .env file:

# OpenAI
OPENAI_API_KEY="your-api-key-here"

# Or Google AI
GOOGLE_GENERATIVE_AI_API_KEY="your-api-key-here"

# Or Anthropic
ANTHROPIC_API_KEY="your-api-key-here"

Refer to AI SDK for more in-depth instructions on how to use the various AI providers (common ones listed here):

• OpenAI
• Google Generative AI
• Anthropic

Start translating

Let's start translating content!

npx langnostic translate

"scripts": {
  // ...other scripts
  "translate": "langnostic translate"
}

The command will automatically detect which strings need translation and generate/update your target locale files.

Using the example project structure and config above that has a single source JSON file at src/locales/en-US.json targeting the locales zh-CN.json and pt-BR.json, the translated files will be generated beside the source file.

├── src
│   └── locales
│       ├── en-US.json
│       ├── pt-BR.json
│       └── zh-CN.json
├── package.json
└── langnostic.config.ts

Markdown/MDX files

To translate Markdown/MDX files, you will need to use the MDX plugin.

Firstly, install the MDX plugin:

npm install @langnostic/plugin-mdx --save-dev

Configure the paths to your Markdown/MDX files. Assuming the following file directory structure:

├── docs
│   └── en-US
│       ├── getting-started.mdx
│       └── introduction.mdx
├── package.json
└── langnostic.config.ts

The following configuration will translate all the .mdx files in the docs/en-US/ directory.

import MdxPlugin from '@langnostic/plugin-mdx';

export default {
  // Other config omitted for brevity...
  groups: [
    {
      name: 'docs',
      plugin: MdxPlugin(),
      paths: [
        {
          source: './docs/en-US/**/*.mdx',
          target: './docs/{locale}/**/*.mdx',
        },
      ],
    },
  ],
} satisfies ConfigType;

Say we have the following source Markdown/MDX file:

---
title: Getting Started
description: Learn how to get started
---

# Getting Started

Welcome to our documentation!

<Alert>
  This is an important note.
</Alert>

Run langnostic translate and the translated Markdown/MDX file will be created:

---
title: 入门指南
description: 学习如何开始
---

# 入门指南

欢迎阅读我们的文档！

<Alert>
  这是一个重要的提示。
</Alert>

The translated file intelligently preserves the frontmatter, Markdown syntax, and any JSX syntax.

In the above example, the final file directory looks like this:

├── docs
│   ├── en-US
│   │   ├── getting-started.langnostic.json
│   │   ├── getting-started.mdx
│   │   ├── introduction.langnostic.json
│   │   └── introduction.mdx
│   └── zh-CN
│       ├── getting-started.mdx
│       └── introduction.mdx
├── package.json
└── langnostic.config.ts

*.langnostic.json files will be created for each source file and they are meant to be committed into the repository. These files track the translation status of the source file and target files so that any changes made to the source file can be compared against its last translated version. This is necessary so that Langnostic translates only the changes made to the source file and not the entire file. You can think of that file as a .git directory for each source file.

Other helpful tips

The langnostic translate command comes with a few helpful flags for an improved developer experience:

Preview changes first

Use the --dry-run flag to get a preview of the strings that will be translated.

npx langnostic translate --dry-run

Debug mode

Use the --debug flag to log the prompts and responses from the AI into the .langnostic folder.

npx langnostic translate --debug