Lingo.dev Docs

Appearance

Translate YAML Files for Backend Frameworks ​

Simplify localization for Ruby on Rails, Laravel, and other backend frameworks with Lingo.dev's powerful YAML translation capabilities.

Quick Setup ​

Create an i18n.json configuration file in your project root:

json
{
  "version": 1,
  "locale": {
    "source": "en",
    "targets": ["ja", "ko", "zh"]
  },
  "buckets": {
    "yaml": {
      "include": ["locales/[locale].yml"]
    }
  }
}

This configuration:

  • Sets English as your source language
  • Targets Japanese, Korean, and Chinese translations
  • Looks for files in the locales folder with locale-based naming (e.g., en.yml, ja.yml)

One Command Translation ​

Translate all your YAML files with a single command:

bash
npx lingo.dev@latest i18n

This automatically:

  1. Reads your source YAML files
  2. Identifies new or modified content
  3. Translates only what's changed
  4. Creates or updates target language files with identical structure

Framework-Specific Features ​

Ruby on Rails Support with Root Keys ​

For frameworks like Rails that use locale-based root keys, use the specialized yaml-root-key bucket type:

json
{
  "version": 1,
  "locale": {
    "source": "en",
    "targets": ["fr", "de", "it"]
  },
  "buckets": {
    "yaml-root-key": {
      "include": ["locales/[locale].yml"]
    }
  }
}

This handles files with locale namespacing:

yaml
en:
  greeting: "Hello"
  farewell: "Goodbye"
yaml
fr:
  greeting: "Bonjour"
  farewell: "Au revoir"

Smart YAML Handling ​

Complex Structure Support ​

Lingo.dev preserves all YAML formatting and structure:

Nested Hierarchies ​

yaml
navigation:
  home: Home
  about:
    team: Our Team
    mission: Our Mission

Multi-line Text ​

yaml
long_text: |
  This is a long piece of text
  that spans multiple lines.
  Lingo.dev will translate it
  while maintaining the format.

Variable Placeholders ​

yaml
welcome: "Welcome, %{name}!"
count_message: "You have %{count} new messages."

Advanced Configuration Options ​

Protect Technical Content with Key Locking ​

Prevent translation of specific keys:

json
"yaml": {
  "include": ["locales/[locale].yml"],
  "lockedKeys": [
    "system/version",
    "config/api_url",
    "branding/name"
  ]
}

Key locking features:

  • Uses forward slash (/) as the separator for nested keys
  • Works with keys containing dots (e.g., config/api.url)
  • Compatible with nested objects and array elements
  • Supports both regular YAML and YAML with root key formats

For more details, see the Key Locking documentation.

Why Developers Choose YAML Translation ​

  1. Framework Compatibility: Perfect for Rails, Laravel, and other backend frameworks
  2. Structure Preservation: Maintains your exact YAML hierarchy and formatting
  3. Format Flexibility: Handles both flat and deeply nested YAML structures
  4. Incremental Updates: Only translates what's changed, saving time and resources
  5. Multi-line Support: Preserves complex text formatting across languages

By integrating Lingo.dev into your development workflow, you get powerful AI-driven translations while maintaining complete control over your localization files and process.