Skill: Translate Content to a New Locale

Translate existing content entries to a target locale, following i18n quality rules.

When to Use

The user wants to translate content, add a new language, or says something like "translate to Turkish", "add German locale", "create French translations", "fill in missing translations", "localize".

Steps

1. Check Project State

Call contentrain_status to understand:

• Supported locales (from config.json → locales.supported).
• Source locale (from config.json → locales.source).
• Available models and their i18n status.
• Any pending changes or validation errors.

2. Determine Target Locale

If the user specified a locale, use it. Otherwise:

• Ask which locale to translate to.
• If the target locale is not in locales.supported, inform the user it needs to be added to the configuration first.

3. Select Models to Translate

Identify which models need translation:

• List all models with i18n: true.
• For each model, call contentrain_content_list(model: "<modelId>", locale: "<sourceLocale>") to get the source content.
• Check which models already have entries in the target locale by calling contentrain_content_list(model: "<modelId>", locale: "<targetLocale>").
• Report the translation gap: how many entries exist in the source locale but not the target.

Ask the user which models to translate, or offer to translate all models with missing entries.

4. Load Vocabulary

Read .contentrain/vocabulary.json for canonical term translations. All vocabulary-defined terms must use the exact translation specified for the target locale — do not create alternative translations.

5. Translate Following i18n Rules

Apply the rules from i18n-quality.md during translation:

#### Translation Quality

• Translate meaning, not words. Produce idiomatic text in the target language.
• Match the sentence structure of the target language, not the source.
• Preserve the tone: if the source is casual, the translation must be casual. If formal, stay formal.
• Fix any machine-translation artifacts: literal translations, incorrect gender agreement, wrong register.

#### Vocabulary Alignment

• Check .contentrain/vocabulary.json for approved translations of terms in the target locale.
• Keep technical terms in their original form if no widely accepted translation exists (API, SDK, CLI, URL).
• Use brand terms exactly as specified per locale in the vocabulary.
• Do not alternate between synonyms — use the same translation for repeated terms throughout.

#### Cultural Adaptation

• Adapt idioms, metaphors, and culturally specific references. Do not translate literally when a cultural equivalent exists.
• Use locale-appropriate date formats, number formats, and units of measurement.
• Replace culturally specific references with locale-appropriate equivalents.
• Avoid idioms that do not translate — use target-language equivalents.

#### String Length Awareness

• Check field max constraints in the model definition.
• Account for expansion ratios: German +30-40%, French +15-25%, Chinese -30-50%.
• If a translation exceeds the field limit, rewrite it shorter. Never truncate mid-word.
• Pay special attention to UI strings (button labels, menu items) with tight space constraints.
• Flag any fields that hit max constraints.

#### Pluralization

• Use correct CLDR plural categories for the target language.
• English: one, other. German: one, other. Russian: one, few, many, other. Arabic: all six categories.

#### Preserve Non-Translatable Content

• Keep relation IDs, slugs, URLs, image paths, and code snippets unchanged — only translate human-readable text.
• Preserve markdown structure, HTML tags, line breaks, and whitespace patterns from the source.
• Entry IDs (object-map keys) remain the same across locales.

6. Kind-Specific Rules

• singleton: Translate all string/text/markdown/richtext fields.
• collection: Translate each entry's fields. Use the same entry IDs across locales.
• document: Translate frontmatter fields and markdown body. Slug may stay the same or be localized (ask the user).
• dictionary: Translate all values. Keys remain identical across locales (e.g., "auth.login" key stays the same, value changes).

7. Present Translations for Review

Show the user a side-by-side comparison:

Model: hero (singleton)
Field: title
  en: "Build faster with AI"
  tr: "AI ile daha hizli gelistirin"

Field: description
  en: "Ship content-driven apps in minutes"
  tr: "Icerik odakli uygulamalari dakikalar icinde yayinlayin"

Wait for user approval. The user may request adjustments to tone, phrasing, or terminology.

7.5. Bulk Copy for New Locales

When translating a model to a brand-new locale, use copy_locale to bootstrap the target locale with source content before translating:

contentrain_bulk({ operation: "copy_locale", model: "<model-id>", source_locale: "en", target_locale: "<target>" })

This creates target locale files with the source content as a starting point. Then translate each entry's values in-place — keys and entry IDs remain identical.

After all translations are saved, re-generate the SDK client so the application picks up the new locale data:

npx contentrain generate

After Translation: SDK Regeneration

New locale data requires SDK client regeneration:

npx contentrain generate

8. Save Translations

After approval, call contentrain_content_save for each model and target locale:

contentrain_content_save(model: "<model-id>", entries: [
  { id: "<same-id>", locale: "<target-locale>", data: { ...translatedFields } }
])

Use the same id (for collections) or slug (for documents) as the source entry to maintain the cross-locale link. Batch all entries for a model in one call.

9. Validate

Call contentrain_validate to verify:

• i18n completeness — all source locale keys exist in the target locale.
• Schema compliance — translated values respect field constraints (min, max, pattern).
• Vocabulary alignment — vocabulary terms match their canonical translations.
• Referential integrity — relation fields are unchanged and still valid.

If validation fails, fix issues and re-save.

10. Submit

Call contentrain_submit to commit the translations:

• Branch: cr/content/{model}/{targetLocale}/{timestamp}.
• Each locale can be submitted independently.

11. Final Summary

Report to the user:

• Models translated: X.
• Entries translated: X.
• Target locale(s): X.
• Vocabulary terms applied: X.
• Any fields that hit max constraints (flagged for review).
• Validation result.
• Submission status.
• Reminder to review translations for nuance that automated checks cannot catch.
• Suggestion: run /contentrain-review to verify overall i18n coverage.

Related Skills

• contentrain-serve — Review translated content in browser
• contentrain-generate — SDK regeneration for new locale data
• contentrain-quality — Translation quality rules
• contentrain — Core architecture and MCP tool catalog