Official YAML Structure
LesliBabel YAML Schema v1 defines the only translation structure managed by the engine. Its purpose is to keep translation keys predictable and portable across Lesli applications and engines.
Canonical Structure
Every translation file follows exactly this hierarchy:
locale → module → bucket → label → value
---
en:
lesli_babel:
labels:
navigation_translations: "Translations"
button_create: "Create label"
message_empty: "No labels were found"
Each level maps directly to LesliBabel's database:
| YAML level | Database representation | Example |
|---|---|---|
| Locale | Locale column in lesli_babel_labels | en |
| Module | lesli_babel_modules.code | lesli_babel |
| Bucket | lesli_babel_buckets.code | labels |
| Label | lesli_babel_labels.text | button_create |
| Value | Value stored in the locale column | Create label |
The complete translation path is:
lesli_babel.labels.button_create
Translation Files
Translation files belong in the owning package's config/locales directory and use the locale in their filename:
config/locales/translations.en.yml
config/locales/translations.es.yml
The filename locale and root YAML locale must match:
# translations.es.yml
---
es:
lesli_babel:
labels:
button_create: "Crear etiqueta"
A file must use:
- UTF-8 encoding.
- One locale root.
- Plain locale keys such as
en, not Ruby-specific symbol keys such as:en. - The module owned by the package.
- Scalar string translation values.
Third-party namespaces such as Devise do not belong in a managed translation file. Keep them in a separate package file such as devise.en.yml; LesliBabel discovers only translations.<locale>.yml files.
Module Codes
The module identifies the application or engine that owns the translation. It must match the registered LesliBabel::Module#code exactly.
Examples:
lesli
lesli_babel
lesli_support
main_app
Lesli engine module codes use lowercase snake_case. A translation file must not create an alternative spelling or alias for an existing module.
Bucket Codes
A bucket groups labels belonging to the same feature, resource, or shared interface area.
Examples:
application
dashboard
labels
shared
tickets
Bucket codes use lowercase snake_case. A bucket is unique inside its module and forms the second segment of the translation path.
Bucket names do not change module ownership. In particular, lesli.shared and lesli.application belong to the lesli module and its core package. They must not be copied into other engine files. An engine-specific bucket such as lesli_support.shared remains owned by lesli_support.
Label Codes
A label is the immutable final segment of a translation path. It uses lowercase snake_case and must not contain spaces, hyphens, or dots.
Valid labels:
title
button_save
column_status
message_not_found
navigation_settings
Invalid labels:
ButtonSave
button-save
button.save
button save
After a label is created, its module, bucket, and label code do not change. A new semantic meaning requires a new label.
Optional Purpose Prefixes
Prefixes are optional. When selected, the prefix is joined to the label before it is stored and becomes part of the immutable label code.
prefix: button
label: save
stored label: button_save
The official prefixes are defined by LesliBabel::Label.prefixes:
| Prefix | Purpose | Example |
|---|---|---|
column | Database or table columns | column_status |
navigation | Navigation items | navigation_settings |
button | Buttons and actions | button_save |
chart | Charts and data visualization | chart_activity |
tab | Tab labels | tab_details |
table | Table-level interface text | table_empty |
toolbar | Toolbar controls | toolbar_search |
view | Page and view text | view_title |
message | Messages and notifications | message_not_found |
Labels without a prefix remain valid when no official prefix describes their purpose. Applications must not invent new prefixes locally; additions belong in LesliBabel::Label.prefixes so the vocabulary remains shared.
Translation Values
A completed translation is a non-empty YAML string:
button_save: "Save"
Always quote values that contain punctuation, interpolation tokens, YAML keywords, leading or trailing whitespace, or characters such as :, #, %, {, and }.
The following value types are not part of Schema v1:
- Nested hashes.
- Arrays.
- Numbers.
- Booleans.
- YAML
nullvalues. - YAML anchors and aliases.
Missing Translations
LesliBabel represents an unresolved value with its complete path wrapped in colons:
message_not_found: ":lesli_babel.labels.message_not_found:"
The marker path must match the module, bucket, and label containing it. A marker is not a completed translation and must not replace an existing translated value during import.
Empty strings are also considered untranslated, but generated files should use the explicit path marker so missing values are visible during development.
Interpolation Tokens
Rails interpolation tokens are supported inside scalar values:
message_welcome: "Welcome, %{name}"
message_results: "%{count} results found"
Every locale for the same label must preserve the same named tokens. Translators may change their order but must not translate, add, or remove token names.
# Valid
en:
lesli_babel:
labels:
message_welcome: "Welcome, %{name}"
es:
lesli_babel:
labels:
message_welcome: "Bienvenido, %{name}"
Nesting Is Not Allowed Below a Bucket
A bucket contains labels directly. Additional grouping levels are invalid:
# Invalid
en:
lesli_babel:
labels:
forms:
button_save: "Save"
The standard representation moves the grouping responsibility to the bucket or label:
# Valid: dedicated bucket
en:
lesli_babel:
label_forms:
button_save: "Save"
or:
# Valid: grouping included in the immutable label
en:
lesli_babel:
labels:
button_form_save: "Save"
Pluralization
Schema v1 stores one scalar value per label and locale. Rails pluralization hashes such as one and other introduce an additional nesting level and are therefore not part of Schema v1.
When an interface requires two forms under Schema v1, store each form as an explicit label and select the label in application code:
message_results_one: "%{count} result"
message_results_other: "%{count} results"
Do not add pluralization hashes to managed translation files until LesliBabel defines a controlled pluralization extension. Existing legacy pluralization structures require migration or an explicit future schema version.
Deterministic Output
Files generated by LesliBabel use stable ordering:
- Locale.
- Module code.
- Bucket code.
- Label code.
Stable ordering makes generated changes easy to review and prevents unrelated YAML diffs.
Invalid Structure Examples
Multiple locales in one file:
en: {}
es: {}
Locale and filename mismatch:
# translations.en.yml
es: {}
Label outside a bucket:
en:
lesli_babel:
button_save: "Save"
Non-scalar value:
en:
lesli_babel:
labels:
navigation_items:
- "Dashboard"
- "Translations"
Schema v1 Checklist
A valid managed file satisfies all of the following:
- The filename follows
translations.<locale>.yml. - The document contains exactly one locale root.
- The root locale matches the filename.
- The module matches the package's registered module code.
- Module, bucket, and label codes follow the naming convention.
- Labels appear directly below buckets.
- Every completed translation is a scalar string.
- Missing-value markers contain the exact complete translation path.
- Interpolation token names match across locales.
- No duplicate module, bucket, or label keys exist.
- No YAML aliases or arbitrary nested structures are present.
This contract is the foundation for the LesliBabel validator, importer, and deployer. Those components must reject invalid input rather than silently transform it into a different translation path.
Last Update: 2026/11/13