Skip to main content

YAML Import

Azbox supports YAML files for translations, commonly used in Ruby on Rails, Symfony, and other frameworks. The format is compatible with Crowdin exports.

When to Use YAML​

  • 💎 Ruby on Rails applications
  • 🎼 Symfony (PHP) projects
  • 📦 Crowdin exports
  • 🔧 Configuration-style translation files

File Format​

Simple Structure (No Root Locale)​

en.yml
welcome:
  title: "Welcome!"
  subtitle: "Get started today"
messages:
  success: "Operation completed"
  error: "Something went wrong"
buttons:
  save: "Save"
  cancel: "Cancel"

With Root Locale (Crowdin Style)​

en.yml
en:
  welcome:
    title: "Welcome!"
    subtitle: "Get started today"
  messages:
    success: "Operation completed"
    error: "Something went wrong"
Automatic Detection

Azbox detects if your file has a locale key at the root (like en:) and handles it automatically.

Key Flattening​

Nested keys are flattened with dots:

# Input
welcome:
  messages:
    greeting: "Hello!"
# Result in Azbox
welcome.messages.greeting → "Hello!"

Complete Example​

English (en.yml):

en:
  app:
    name: "My Application"
    tagline: "Build something amazing"
  
  navigation:
    home: "Home"
    about: "About Us"
    contact: "Contact"
    settings: "Settings"
  
  auth:
    login: "Log In"
    logout: "Log Out"
    signup: "Sign Up"
    forgot_password: "Forgot Password?"
  
  messages:
    welcome: "Welcome back, %{name}!"
    goodbye: "See you soon!"
    error: "An error occurred"
    success: "Operation successful"
  
  errors:
    not_found: "Page not found"
    unauthorized: "You are not authorized"
    server_error: "Server error, please try again"

Spanish (es.yml):

es:
  app:
    name: "Mi Aplicación"
    tagline: "Construye algo increíble"
  
  navigation:
    home: "Inicio"
    about: "Nosotros"
    contact: "Contacto"
    settings: "Configuración"
  
  auth:
    login: "Iniciar Sesión"
    logout: "Cerrar Sesión"
    signup: "Registrarse"
    forgot_password: "¿Olvidaste tu contraseña?"
  
  messages:
    welcome: "¡Bienvenido de nuevo, %{name}!"
    goodbye: "¡Hasta pronto!"
    error: "Ocurrió un error"
    success: "Operación exitosa"
  
  errors:
    not_found: "Página no encontrada"
    unauthorized: "No tienes autorización"
    server_error: "Error del servidor, intenta de nuevo"

How to Import in Azbox​

Step 1: Open Import Dialog​

Click Import in your project dashboard.

Step 2: Select Format​

Choose YAML (.yaml) from the dropdown.

Step 3: Select Language​

Pick the target language for this file.

Step 4: Import​

Click Import and select your .yaml or .yml file.

Step 5: Review Results​

Check imported keywords and any warnings.

What Gets Imported​

ContentImportedNotes
String values✅ YesFlattened with dots
Nested objects✅ Yesa.b.c format
Lists/Arrays⚠️ ConvertedJoined with newlines
Empty values⚠️ SkippedWarning generated
Root locale key✅ DetectedRemoved from key path

Interpolation​

YAML commonly uses %{variable} for interpolation:

greeting: "Hello, %{name}!"
items: "You have %{count} items"

These are preserved as-is in Azbox.

Rails Pluralization​

Rails uses special keys for plurals:

en:
  items:
    zero: "No items"
    one: "One item"
    other: "%{count} items"

Azbox imports each as a separate key:

  • items.zero → "No items"
  • items.one → "One item"
  • items.other → %{count} items

File Naming​

Common patterns (locale auto-detected):

FilenameDetected Locale
en.ymlen
es.ymles
fr-CA.ymlfr-ca
locales/en.ymlen

Usage Examples​

Ruby on Rails​

# In views
<%= t('messages.welcome', name: @user.name) %>

# In controllers
flash[:notice] = t('messages.success')

Symfony (PHP)​

// In Twig
{{ 'messages.welcome'|trans({'%name%': user.name}) }}

// In PHP
$translator->trans('messages.success');

Best Practices​

  1. One file per language — en.yml, es.yml, fr.yml
  2. Use root locale — Helps identify the language
  3. Consistent nesting — Same structure across all files
  4. Meaningful namespaces — auth., errors., messages.
  5. Quote special values — Strings starting with @, *, etc.

Common Issues​

YAML Syntax Errors​

# ❌ Wrong - unquoted colon
message: Welcome: friend

# ✅ Correct - quoted
message: "Welcome: friend"

Special Characters​

# ❌ Wrong - unquoted special char
title: @username

# ✅ Correct - quoted
title: "@username"

Multiline Strings​

# Block scalar (preserves newlines)
description: |
  Line 1
  Line 2
  Line 3

# Folded scalar (joins lines)
description: >
  This is a long
  description that
  will be one line.

Project Structure​

config/locales/
├── en.yml      ← Import as English
├── es.yml      ← Import as Spanish
├── fr.yml      ← Import as French
└── de.yml      ← Import as German

Or with namespaces:

config/locales/
├── en/
│   ├── common.yml
│   ├── errors.yml
│   └── models.yml
├── es/
│   ├── common.yml
│   ├── errors.yml
│   └── models.yml