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

# Translations

<p className="lead">
  Translations define localized text strings for your agent. Each translation has a key and a set of language-specific values, so the agent can respond in the user's configured language.
</p>

Translations are paired with [languages](/adk/reference/languages): every translation key must include an entry for the default language and for each additional language the project supports.

## Location

Translations are defined in:

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
config/translations.yaml
```

Translations are listed under the `translations` key. The file is optional.

## What a translation contains

| Field          | Description                                                                          |
| -------------- | ------------------------------------------------------------------------------------ |
| `name`         | Translation key identifier. Referenced in rules, topics, and flows as `{{tr:name}}`. |
| `translations` | Map of BCP 47 language codes to localized text strings.                              |

## Example

```yaml theme={"theme":{"light":"github-light","dark":"github-dark"}}
translations:
  - name: greeting
    translations:
      en-GB: Hello, how can I help you?
      fr-FR: Bonjour, comment puis-je vous aider?
  - name: farewell
    translations:
      en-GB: Goodbye, have a nice day!
      fr-FR: Au revoir, bonne journée!
```

## Validation

* `name` is required and cannot be empty.
* Each translation must have at least one language entry.
* If `agent_settings/languages.yaml` is present, every configured language (default + additional) must have an entry in each translation. Missing languages cause a validation error.
* Duplicate translation names are not allowed.

## Referencing translations

Translations are referenced by name in rules, topics, and flow prompts:

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
{{tr:greeting}}
```

At runtime, the platform resolves the reference to the localized string for the current conversation language.

## Best practices

* use descriptive translation keys that indicate purpose (e.g. `greeting`, `error_not_found`, `confirmation_prompt`)
* ensure every configured language has an entry for every translation key before pushing
* keep translation values consistent in tone and meaning across languages
* prefer translation references over hard-coded strings in prompts when an agent supports more than one language

<Warning>
  **Translation keys are shared across channels**

  A translation key resolves to the same value on voice and chat. Use [SMS templates](/adk/reference/sms) when you need channel-specific copy.
</Warning>

## Related pages

<CardGroup>
  <Card title="Languages" href="/adk/reference/languages">
    Configure the default and additional languages that translations must cover.
  </Card>

  <Card title="Agent settings" href="/adk/reference/agent_settings">
    See how translations fit alongside other agent configuration.
  </Card>

  <Card title="SMS templates" href="/adk/reference/sms">
    Reusable SMS bodies, complementary to translations for channel-specific copy.
  </Card>
</CardGroup>