# Internationalization

Are you interested in bringing Actual to a broader audience by translating and localizing the app into new languages? Great! This guide will show you how to get started. Adding translations can be a great first step into contributing to open-source software.

## Translating existing strings

Actual uses [Weblate](https://hosted.weblate.org/projects/actualbudget/actual) to manage all translations. In particular, we use Weblate's "suggestions" system to maintain high-quality translations.

:::note Pull Requests

We do not accept GitHub Pull Requests modifying translation files—any PRs in the translations repository will be automatically closed.

:::

### Suggesting a new translation

To suggest a translation for a language you are familiar with, just find a string you'd like to translate, fill in a translation, and hit "Suggest." This will then give others the opportunity to vote on the most accurate translation. Check out the [Weblate docs](https://docs.weblate.org/en/latest/user/translating.html) for more details.

Please only fill in translations that you are confident in, and be sure to include the same formatting markers as the English text (example: `<1>English</1>` -> `<1>Anglais</1>`).

### Voting on existing suggestions

To help vote on high-quality strings, click on "Strings with suggestions" from a language page, and use the thumbs-up or thumbs-down icons to vote. If you click thumbs-down, it's always helpful to provide a reason so that the original translator can improve.

## Marking new strings for translation

Developing translated software requires that every text shown to the user passes through a translation function. Actual uses [i18next](https://www.i18next.com/) to achieve this goal.

Strings in Actual are translated by their natural English language version. The project does not use artificial keys to select the appropriate translated text from the message catalog.

:::note Using natural language keys

Consider the text `"Welcome to Actual Budget"`. When marking strings for translation using natural language, this string also becomes the key used to translate it into other languages. This is in contrast to a commonly used alternative of using artificial keys, which would look like `"text_welcome"`. Actual Budget **does not** use these keys.

:::

When preparing your translatable strings, please use complete units to translate. If there is a cohesive paragraph with multiple sentences, mark the entire paragraph as one translatable string. Do not split it into multiple texts.

The translation framework provides two primary methods for translation:

### `t()` Function

The `t()` function is the simplest form of translation, it accepts the text to be translated and an optional object with interpolation variables. We're using the `i18next` singleton instance. You can use the hook within React components to get a reference to it.

```javascript
import { useTranslation } from 'react-i18next';

function MyComponent() {
  const { t } = useTranslation();

  return <button aria-label={t('Hello World')} />;
}
```

At runtime, it will select the translation from the currently active locale. You can also add variables to [interpolate](https://www.i18next.com/translation-function/interpolation):

```javascript
const withPlaceholder = t('Welcome home, {{name}}!', { name: 'Anita' });
```

For [pluralization](https://www.i18next.com/translation-function/plurals), please use the plural form for the default text. The placeholder variable **must** be named `count`:

```javascript
const manyItems = t('You selected {{count}} items', { count: 4 });
```

i18next will take care of proper pluralization rules in the currently active language and provide multiple different forms if required.

### `<Trans>` Component

When translating text with simple HTML tags or other React components, we ask that you use the [`<Trans>` component](https://react.i18next.com/latest/trans-component).

```javascript
import { Trans } from 'react-i18next';

function MyComponent() {
  return (
    <Trans>
      Click <Link href={url}>here</Link> to become a millionaire.
    </Trans>
  );
}
```

#### Interpolation with `<Trans>`

Handling placeholder variables and pluralization within the `<Trans>` React component is handled slightly differently. For more details, please refer to [i18next-react's documentation](https://react.i18next.com/latest/trans-component#interpolation).

```javascript
import { Trans } from 'react-i18next';

function MyComponent() {
  const person = { name: "Pedro" };
  // You can use an object literal within <Trans>!
  return (
    <Trans>
      Your name is {{ name: person.name }}.
    </Trans>
  );
  // This will result in the translation string:
  // "Your name is {{name}}."
}
```
