# Draft Translations for Another Locale with AI

> Source: https://agilitycms.com/docs/editors/ai-recipe-translate-content

An AI assistant connected to Agility can read content in one locale, translate it, and save the translation into another locale as a linked copy, ready for a fluent reviewer to check. This works well for a handful of items, for adapting tone while translating, or when you want to give the assistant instructions about your terminology.

If you haven't connected an assistant yet, start with [Using AI Assistants with Agility CMS](/docs/editors/using-ai-assistants-with-agility).

> **Prefer to translate inside Agility?** If the [DeepL app](/docs/apps/deepl) is installed on your instance, you can translate without an assistant: **Save & Localize** and **Copy to Locale(s)** can translate as they copy, and the DeepL panel translates individual fields while you edit. See [Copying and Translating Content Across Locales](/docs/editors/copying-and-translating-content) and [Translating Content with DeepL](/docs/editors/translating-content-with-deepl). Both are in private beta.

## How locales work (read this first)

A few facts about locales decide what this recipe can and can't do. See [Working with Localized Content](/docs/editors/working-with-localized-content) for the full picture.

- **A locale is a parallel space for your content, not a translation of it.** A new locale starts empty. Content appears there only when someone copies or creates it.
- **The target locale must already exist.** Administrators add locales under **Settings** > **Locales**. The assistant can't add one for you. See [Locales](/docs/editors/locales).
- **Copies stay linked.** When content is copied into another locale, Agility treats the two versions as the same item in two languages, and switching locale while editing takes you to its counterpart. The assistant creates this link by saving the translation into the target locale under the **same content ID** as the original.
- **Editing one locale doesn't change the others**, except for fields your developers marked **Constant across all languages**. Those are shared by every locale on purpose, so don't ask the assistant to translate them.
- **Shared lists aren't copied.** Tags, categories and other shared content stay in the locale you built them in. If translated items link to them, localize those lists as a separate task first.
- **Same language, different region is a copy, not a translation.** en-us to en-ca needs regional adjustments (spelling, legal wording), not translation. You can ask the assistant for exactly that.

## Goal

Draft translations of chosen content items from your source locale (for example `en-us`) into a target locale (for example `fr-ca`), saved to Staging in the target locale, linked to the originals, for a fluent reviewer to approve.

## Step 1: Check the locales and pick the items (read-only)

```text
In the [instance name] Agility instance, list the locales. Then, in [en-us],
list the 10 most recently modified items in the [Blog Posts] content list,
and tell me which of them already exist in [fr-ca].
Don't change anything yet.
```

## Step 2: Draft the translations, then save

```text
Translate items [IDs or titles] from en-us into Canadian French for the
fr-ca locale.

Rules:
- Translate the text fields only: title, summary, body and SEO fields.
- Keep HTML, links and formatting in rich text exactly as they are.
- Don't translate our product names: [Agility CMS, Web Studio].
- Leave images, dates, numbers, dropdowns and linked items unchanged.
- Don't touch fields that are constant across all languages.
- If an item has a URL slug field, translate it too, in lowercase words
  joined by hyphens.

Show me the translated title and summary for each item first.
Don't save yet.
```

Check the samples. When they look right:

```text
Save each translation into the fr-ca locale using the same content ID as the
en-us original, so the two stay linked. Skip any item that already exists in
fr-ca. Then list what you saved, with links to open each item in Agility.
```

## What the assistant does

In plain words, behind the scenes:

1. **Checks the locales** that exist in the instance (`get_locales`).
2. **Reads the content model** so it knows which fields are text and which aren't (`get_content_model_details`).
3. **Reads each source item** in the source locale (`get_content_items`, `get_content_item`).
4. **Translates the text itself.** The translation comes from the AI model you're using, not from DeepL.
5. **Saves each translation into the target locale** under the original content ID (`save_content_items`), which creates the linked locale copy. Saves land in **Staging** in the target locale. Nothing is published, and the source locale is untouched.

## Review the result in Agility

1. In **Content**, switch to the target locale with the locale selector and open the content list.
2. Open each translated item. Have a fluent speaker read it, especially headings, calls to action and legal or product wording.
3. Check that images, links, dates and linked items look right for this market. If an image contains words, it may need a localized version.
4. Switch the locale selector back to the source locale while editing to confirm the item opens its counterpart, which shows the two are linked.
5. Use **Preview** in the target locale, then publish or request approval. Each locale publishes on its own schedule. See [Previewing, Publishing, and Content States](/docs/editors/preview-and-publishing).

## Variations

- **Regional variant instead of translation.** "Copy these items from en-us into en-gb. Change US spelling to British spelling and nothing else."
- **Update an existing translation.** "The en-us version of item [ID] changed. Show me what's different from the fr-ca version, then update only those parts in fr-ca." Locales don't sync on their own, so this is a good way to keep them current.
- **Provide a glossary.** Paste a short list of approved translations for your key terms and say "Always use these."
- **Check coverage.** "Which items in Blog Posts exist in en-us but not in fr-ca?"
- **Run it fully automated.** A scheduled job or agent can translate new source items as they appear, save them into the target locale, check them (every text field translated, markup and links intact, glossary terms used) and publish the ones that pass with `publish_content`. Many teams still want a fluent reviewer to read translations before they go live, but it's your organization's choice. See [Choose how much the assistant does](/docs/editors/using-ai-assistants-with-agility#choose-how-much-the-assistant-does).

## Pitfalls

- **Pages need initializing first.** This recipe is for content items. To bring a page into another locale, initialize it in Agility first, which copies the page structure and components (and can translate them with DeepL). See [Copying and Translating Content Across Locales](/docs/editors/copying-and-translating-content) and [Initialize a Page in Another Locale](/docs/editors/initialize-a-page-in-another-locale).
- **Unlinked copies.** If the assistant saves a translation as a brand new item instead of under the original content ID, it won't be linked to the original. Check with the locale selector. If you find a stray copy, remove it in Agility yourself once you've confirmed which one it is, then ask the assistant to save the translation again under the original content ID.
- **Broken markup.** Rich text must come back with the same HTML. Spot-check links and formatting.
- **Machine translation isn't review.** Any AI translation can be fluent and still wrong. A fluent reviewer catches things automated checks can't, which is why many teams keep one for translations even when other content publishes automatically.
- **Overwriting a reviewed translation.** If an item already exists in the target locale, saving again replaces its fields in a new Staging version. Ask the assistant to skip existing items unless you mean to update them.

## Related articles

- [Using AI Assistants with Agility CMS](/docs/editors/using-ai-assistants-with-agility)
- [Working with Localized Content](/docs/editors/working-with-localized-content)
- [Copying and Translating Content Across Locales](/docs/editors/copying-and-translating-content)
- [Translating Content with DeepL](/docs/editors/translating-content-with-deepl)
- [Locales](/docs/editors/locales)