Translation File Formats and Structure
You'll learn: How JSON, YAML, and PO file formats organize translations and which format best fits your maintainability needs.
When building internationalized sites, you need a structured way to store translations separate from your code. Think of translation files as dictionaries—organized collections of key-value pairs where keys identify messages and values provide the translated text.
JSON: Developer-Friendly, Simple Structure
JSON is the most common format in web development:
{
"nav.home": "Home",
"nav.about": "About Us",
"greeting": "Hello, {name}!"
}
Pros: Native JavaScript support, easy to parse, well-understood by developers. Cons: No comments allowed (officially), verbose with nested structures, quotes everywhere.
YAML: Human-Readable, Hierarchical
YAML emphasizes readability with indentation-based nesting:
nav:
home: Home
about: About Us
greeting: "Hello, {name}!"
# Comments supported!
Pros: Cleaner syntax, supports comments for translator notes, natural hierarchy. Cons: Whitespace-sensitive (error-prone), requires parsing library in browsers.
PO (Portable Object): Translation-Tool Standard
PO files come from the gettext ecosystem, designed specifically for localization workflows:
#: src/navigation.js
msgid "nav.home"
msgstr "Home"
msgid "greeting"
msgstr "Hello, {name}!"
Pros: Industry-standard format, translator-friendly, supports context and plurals, excellent tool ecosystem. Cons: Requires compilation to binary format (.mo) for performance, unfamiliar syntax for web developers.
Choosing the Right Format
JSON suits small-to-medium projects where developers manage translations. YAML works well for configuration-heavy setups with technical writers. PO excels in professional translation workflows with dedicated translators using CAT (Computer-Assisted Translation) tools.
Key Takeaway: JSON offers simplicity for dev-managed translations, YAML prioritizes readability and comments, while PO provides the most robust professional translation toolchain—choose based on your team's workflow, not just developer preference.