> ## Documentation Index
> Fetch the complete documentation index at: https://docs.honyaku.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Setting up

> Learn how to update translations manually or automatically

## Creating a language file

We support any i18n library. However, to help AI understand the context and generate better translations, we recommend having "description" fields in your translation files to provide more context for each translation key.

### Pattern 1

Schema:

```ts theme={null}
Record<string, { text: string; description: string }>
```

Example:

```json theme={null}
{
  "save": {
    "text": "Save",
    "description": "A button label that allows users to save their changes or progress."
  },
  "cancel": {
      "text": "Cancel",
      "description": "A button label that allows users to abort an action or close a dialog without making changes."
  },
}
```

You can convert this format to a simpler format that your i18n library uses:

```ts theme={null}
import en from "@/i18n/en.json"

const enMessages = loadMessages(en)

function loadMessages(messages: Record<string, { text: string }>): Record<string, string> {
  return Object.fromEntries(Object.entries(messages).map(([key, value]) => [key, value.text]))
}
```

### Pattern 2

Schema:

```ts theme={null}
{ key: string; text: string; description: string }[]
```

Example:

```json theme={null}
[
  {
    "key": "save",
    "text": "Save",
    "description": "A button label that allows users to save their changes or progress."
  },
  {
    "key": "cancel",
    "text": "Cancel",
    "description": "A button label that allows users to abort an action or close a dialog without making changes."
  },
]
```

You can convert this format to a simpler format that your i18n library uses:

```ts theme={null}
import en from "@/i18n/en.json"

const enMessages = loadMessages(en)

function loadMessages(messages: { key: string; text: string }[]): Record<string, string> {
  return Object.fromEntries(messages.map(({ key, text }) => [key, text]))
}
```

## Generating translations

For generating translations, it's highly recommended to use one of our [integrations](/integrations).

You can edit translations manually using our web editor if you find any mistakes.

If you need a list of available locales for locale switcher or other purposes, check out [@honyaku-dev/locales](https://www.npmjs.com/package/@honyaku-dev/locales) package.

## Loading translations

Using our integration with CI/CD, you can automatically update translations when new translation keys are added, or when messages are modified.

After new translations are generated, the changes are automatically committed to your repository. Because there is some delay before those changes are committed, it is highly recommended to prepare a fallback mechanism when loading translations.

You can use a code snippet from [our example project](https://github.com/honyaku-dev/honyaku-example/blob/main/i18n/request.ts).

```typescript request.ts theme={null}
import { getRequestConfig } from "next-intl/server";
import { hasLocale } from "next-intl";
import { routing } from "./routing";
import { loadLocale, loadMessages } from "@/lib/honyaku";
import en from "@/messages/en.json"

const enMessages = loadMessages(en);

export default getRequestConfig(async ({ requestLocale }) => {
  const requested = await requestLocale;
  const locale = hasLocale(routing.locales, requested)
    ? requested
    : routing.defaultLocale;

  const messages = await loadLocale(locale);
  return {
    locale,
    messages: {
      ...enMessages,
      ...messages,
    }
  };
});
```

## Updating translations

If you use coding agents, you can use our [update-translations](https://github.com/honyaku-dev/update-translations) skill.

Install the skill by simply running this command:

```
npx skills add honyaku-dev/update-translations
```

Every time a coding agent inserts a new user message, it will update the language file using this skill.

Alternatively, you can manually trigger `/update-translations` and let the coding agent read unstaged / uncommitted changes and update the language file accordingly.