> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/discordplace/discord.place/llms.txt
> Use this file to discover all available pages before exploring further.

# Contributing Translations

> Help translate discord.place into new languages or improve existing translations.

discord.place has full internationalization support for both the client (website) and the server (API/bot). Translations live in JSON files under the respective `locales/` directories and are maintained by community contributors.

## Currently Available Locales

<CardGroup cols={3}>
  <Card title="English" icon="🇺🇸">
    **Code:** `en`\
    **Files:** `client/locales/en.json`, `server/src/locales/en.json`\
    Default locale for the platform.
  </Card>

  <Card title="Turkish" icon="🇹🇷">
    **Code:** `tr`\
    **Files:** `client/locales/tr.json`, `server/src/locales/tr.json`
  </Card>

  <Card title="Azerbaijani" icon="🇦🇿">
    **Code:** `az`\
    **Files:** `client/locales/az.json`\
    Client-only locale.
  </Card>
</CardGroup>

## Locale File Format

Both client and server locale files use a flat or nested JSON structure:

```json theme={null}
{
  "key": "value",
  "nested.key": "translated value"
}
```

Use the existing English file as the authoritative reference when translating — it always contains the full set of keys.

## Contributing to an Existing Translation

If your language already exists in the `locales/` directory, you can improve it by filling in missing keys or correcting inaccurate translations.

<Tabs>
  <Tab title="Client">
    <Steps>
      <Step title="Fork and clone the repository">
        Fork [discord.place on GitHub](https://github.com/discordplace/discord.place) and clone your fork:

        ```bash theme={null}
        git clone https://github.com/YOUR_USERNAME/discord.place.git
        cd discord.place
        ```
      </Step>

      <Step title="Create a translation branch">
        ```bash theme={null}
        git checkout -b feat/i18n-update-turkish-client
        ```
      </Step>

      <Step title="Edit the locale file">
        Open `client/locales/<code>.json` (e.g., `client/locales/tr.json`) and add translations for any missing keys or correct existing ones. Use `client/locales/en.json` as the reference for all available keys.
      </Step>

      <Step title="Commit your changes">
        Follow the Conventional Commits format with an `i18n` scope:

        ```bash theme={null}
        git commit -m "feat(i18n): update Turkish client translations"
        ```
      </Step>

      <Step title="Push and open a pull request">
        ```bash theme={null}
        git push origin feat/i18n-update-turkish-client
        ```

        Open a pull request against the `main` branch of the original repository.
      </Step>
    </Steps>
  </Tab>

  <Tab title="Server">
    <Steps>
      <Step title="Fork and clone the repository">
        Fork [discord.place on GitHub](https://github.com/discordplace/discord.place) and clone your fork:

        ```bash theme={null}
        git clone https://github.com/YOUR_USERNAME/discord.place.git
        cd discord.place
        ```
      </Step>

      <Step title="Create a translation branch">
        ```bash theme={null}
        git checkout -b feat/i18n-update-turkish-server
        ```
      </Step>

      <Step title="Edit the locale file">
        Open `server/src/locales/<code>.json` (e.g., `server/src/locales/tr.json`) and add translations for any missing keys or correct existing ones. Use `server/src/locales/en.json` as the reference for all available keys.
      </Step>

      <Step title="Commit your changes">
        ```bash theme={null}
        git commit -m "feat(i18n): update Turkish server translations"
        ```
      </Step>

      <Step title="Push and open a pull request">
        ```bash theme={null}
        git push origin feat/i18n-update-turkish-server
        ```

        Open a pull request against the `main` branch of the original repository.
      </Step>
    </Steps>
  </Tab>
</Tabs>

## Adding a New Language

<Tabs>
  <Tab title="Client">
    <Steps>
      <Step title="Create the locale JSON file">
        Create a new file at `client/locales/xx.json`, where `xx` is the [ISO 639-1 language code](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) for your language (e.g., `fr.json` for French). Copy the keys from `en.json` and translate the values.

        ```json theme={null}
        {
          "key": "translated value",
          "nested.key": "another translated value"
        }
        ```
      </Step>

      <Step title="Register the language in client/config.js">
        Open `client/config.js` and add your language to the `availableLocales` array:

        ```js theme={null}
        {
          name: 'French',
          code: 'fr',
          dateFnsKey: 'fr',
          flag: '🇫🇷',
          countryCode: 'fr'
        }
        ```
      </Step>

      <Step title="Import the locale file">
        Open `client/stores/language/index.js` and add an import for your new locale file:

        ```js theme={null}
        import fr from '@/locales/fr.json';
        ```
      </Step>

      <Step title="Add to localeContents">
        In the same file (`client/stores/language/index.js`), add your locale to the `localeContents` object:

        ```js theme={null}
        const localeContents = {
          en,
          tr,
          az,
          fr  // add your locale here
        };
        ```
      </Step>

      <Step title="Add translations to the JSON file">
        Fill in all translation keys in your new `client/locales/xx.json` file. Use `client/locales/en.json` as the reference to ensure you cover all keys.
      </Step>

      <Step title="Commit and open a pull request">
        ```bash theme={null}
        git commit -m "feat(i18n): add French locale support"
        git push origin feat/i18n-add-french
        ```

        Open a pull request against the `main` branch.
      </Step>
    </Steps>
  </Tab>

  <Tab title="Server">
    <Steps>
      <Step title="Create the locale JSON file">
        Create a new file at `server/src/locales/xx.json`, where `xx` is the ISO 639-1 language code for your language (e.g., `fr.json` for French). Copy the keys from `en.json` and translate the values:

        ```json theme={null}
        {
          "key": "translated value",
          "nested.key": "another translated value"
        }
        ```
      </Step>

      <Step title="Register the locale in server/config.yml">
        Open `server/config.yml` and add your language as an object to the `availableLocales` array:

        ```yaml theme={null}
        availableLocales:
          - name: 'English'
            code: 'en'
            flag: '🇺🇸'
            default: true
            countryCode: 'us'
          - name: 'French'
            code: 'fr'
            flag: '🇫🇷'
            countryCode: 'fr'
        ```
      </Step>

      <Step title="Add translations to the JSON file">
        Fill in all translation keys in your new `server/src/locales/xx.json` file. Use `server/src/locales/en.json` as the reference.
      </Step>

      <Step title="Commit and open a pull request">
        ```bash theme={null}
        git commit -m "feat(i18n): add French server locale"
        git push origin feat/i18n-add-french-server
        ```

        Open a pull request against the `main` branch.
      </Step>
    </Steps>
  </Tab>
</Tabs>

## Changing the Default Locale

If you are self-hosting and need to change the default locale away from English, two additional changes are required beyond adding the locale:

1. Set the `default: true` flag on your chosen locale in the `availableLocales` array in `client/config.js` (and remove it from the current default).
2. Update the `DEFAULT_LOCALE_CODE` environment variable in `.github/workflows/client-validate-locale-files.yml` to match the new default locale code. Without this change, the locale validation workflow will produce unnecessary errors.

<Warning>
  Not all languages are supported by the Discord client. Before adding a new language, verify that Discord supports it natively. Users may see untranslated strings from Discord itself (such as OAuth prompts) even if the discord.place interface is fully translated.
</Warning>

## Validation

The repository includes automated GitHub Actions workflows that validate locale files on pull requests targeting `client/locales/**`. These checks ensure that locale files are well-formed JSON and that no required keys are missing relative to the default locale. Your PR must pass these checks before it can be merged.

## Additional Resources

* For self-hosting locale configuration details, see the [Localization guide](/self-hosting/localization).
* For general contribution guidance (branches, commits, PRs), see [Contributing Guidelines](/contributing/guidelines).
* The full list of translation keys is in [`client/locales/en.json`](https://github.com/discordplace/discord.place/blob/main/client/locales/en.json) and [`server/src/locales/en.json`](https://github.com/discordplace/discord.place/blob/main/server/src/locales/en.json).