---
title: Quick start
description: Get started with Langnostic in 5 minutes
---

:::info
We're polishing up Langnostic for a public release and the code will be open
sourced soon. Langnostic will be free for open source projects and commercial
projects can purchase a business license for a reasonable one-time fee. If
you're interested in using Langnostic, just [send us an
email](mailto:team@greatfrontend.com).
:::

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:

```package-install
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.

```diff title=".gitignore"
.langnostic
```

## Initialize configuration

Initialize a default configuration file.

```package-install
npx langnostic init
```

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

```typescript title="langnostic.config.ts"
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`:

```typescript title="langnostic.config.ts"
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](https://ai-sdk.dev/), 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](https://ai-sdk.dev/providers/ai-sdk-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:

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

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

```typescript title="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:

```bash title=".env"
# 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](https://ai-sdk.dev/providers/ai-sdk-providers) for more in-depth instructions on how to use the various AI providers (common ones listed here):

- [OpenAI](https://ai-sdk.dev/providers/ai-sdk-providers/openai)
- [Google Generative AI](https://ai-sdk.dev/providers/ai-sdk-providers/google-generative-ai)
- [Anthropic](https://ai-sdk.dev/providers/ai-sdk-providers/anthropic)

## Start translating

Let's start translating content!

```package-install
npx langnostic translate
```

:::info
We recommend adding `langnostic translate` into the `scripts` field of your `package.json`.

```json title="package.json"
"scripts": {
  // ...other scripts
  "translate": "langnostic translate"
}
```

And you'll be able to translate via the command `npm run 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:

```package-install
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.

```typescript title="langnostic.config.ts"
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:

```mdx title="docs/en-US/getting-started.mdx"
---
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:

```mdx title="docs/zh-CN/getting-started.mdx"
---
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.

```package-install
npx langnostic translate --dry-run
```

### Debug mode

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

```package-install
npx langnostic translate --debug
```