> For the complete documentation index, see [llms.txt](https://docs.bird.com/applications/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.bird.com/applications/content/translation-files/creating-and-using-translation-files.md).
# Creating and using translation files
Translation files allow you to dynamically translate content in templates based on the recipient's locale. Here's how to set up and use translation files to create a localised welcome email.
## Step 1: Prepare the Translation File
1. **File Format:**\
Use a CSV file with the following structure:
* Row Key (locale): Represents the locale (e.g., `en-US`, `fr-FR`, `es-ES`).
* Column Headers: Keys for the sections of the template that require translation (e.g., header, body).
2. **Example File:** `welcome_email_translations.csv`
| locale | header | body |
| ------ | -------------------- | ------------------------------------------------ |
| en-US | Welcome to Bird! | We can't wait for you to get started with Inbox. |
| fr-FR | Bienvenue chez Bird! | Nous avons hâte que vous commenciez avec Inbox. |
| es-ES | ¡Bienvenido a Bird! | Estamos ansiosos por que empieces con Inbox. |
3. **Save the File:**
* Save it as welcome\_email\_translations.csv.
## Step 2: Upload the Translation File
1. Go to the **Content > Translation Files** section in Bird.
2. Click **Upload Translation File**.
3. Select `welcome_email_translations.csv` and upload it.
4. Confirm the file upload is successful.
## Step 3: Use Translations in the Email Template
1. **Set the Locale:**\
Assign the recipient's locale to a variable, typically based on their profile attribute. You can also use any custom attribute combination as long as it matches the format in your translation file.\
\
`{% assign locale = contact.attributes.locale %}`
2. **Fetch Translations:**\
Use assign or capture to retrieve the relevant translation from the file using the render tag.\
\
`{% assign header = "welcome_email_translations/header" | t: locale %}`\
`{% assign body = "welcome_email_translations/body" | t: locale %}`
3. **Render the Template:**\
Insert the translations dynamically into your email content. You can also render the translations directly into the variable rather than assigning them first\
\
`{{ header }}
`\
`{{ "welcome_email_translations/body" | t: locale }}
`
#### Complete Template Example
```html
{% assign locale = contact.attributes.locale %}
{% assign header = "welcome_email_translations/header" | t: locale %}
{% assign body = "welcome_email_translations/body" | t: locale %}
{{ header }}
{{ body }}
```
## Step 4: Test Your Translations
**Send a Test Email:**
* Use test contacts with specific locales (e.g. `en-US`, `fr-FR`, `es-ES`) to ensure the translations are applied correctly.
### Best Practices for Using Translation Files
1. **Include fallbacks**\
Always include fallback translations in case a locale-specific translation is missing. For example in the below if the locale is missing it will fallback to en-US, and if that is missing default back to the text “Welcome to Bird”.\
\
`{% assign header = "welcome_email_translations/header" | t: locale, "en-US" | default: "Welcome to Bird!" %}`
2. **Standardise Locale Codes:**\
Ensure consistent locales (e.g. `en-US`, `fr-FR`, `es-ES`) are used across all translation files.
3. **Regular Updates:**\
Keep translation files up-to-date as content changes to maintain consistency across languages.
4. Test Thoroughly:\
Regularly test templates after adding or updating translations to ensure they render correctly.
### Outcome
Using the example above, a French recipient (locale = "fr-FR") will receive:\
**Header:** Bienvenue chez Bird!\
**Body:** Nous avons hâte que vous commenciez avec Inbox.
An English recipient (locale = "en-EN") will receive:\
**Header:** Welcome to Bird!\
**Body:** We can't wait for you to get started with Inbox.
This approach simplifies localisation, ensuring consistent messaging while reducing template duplication.
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://docs.bird.com/applications/content/translation-files/creating-and-using-translation-files.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.