File Formats

Babelize supports multiple file formats commonly used in software localization and content management. This guide explains each format and any special handling considerations.

Supported Formats

JSON

JSON is the most commonly used format for web application localization.

Supported Structures

Flat structure:

{
  "greeting": "Hello",
  "farewell": "Goodbye"
}

Nested structure:

{
  "messages": {
    "greeting": "Hello",
    "farewell": "Goodbye"
  }
}

Arrays:

{
  "items": ["First item", "Second item"]
}

Handling Notes

• Keys are preserved exactly as provided
• Numeric values are not translated
• Boolean values are preserved
• Null values are preserved

YAML

YAML files are handled similarly to JSON with additional considerations.

Supported Structures

messages:
  greeting: Hello
  farewell: Goodbye
  
items:
  - First item
  - Second item

Handling Notes

• Comments are preserved
• Anchors and aliases are resolved before translation
• Multi-line strings maintain their format
• Indentation is preserved

Markdown

Markdown files are parsed to identify translatable content while preserving structure.

What Gets Translated

• Headings
• Paragraphs
• List items
• Blockquotes
• Table cells

What Gets Preserved

• Code blocks (inline and fenced)
• HTML tags (configurable)
• Links (URL preserved, text translated)
• Image alt text (translated)
• Frontmatter (YAML, optional)

Example

Source:

# Welcome

This is a paragraph with **bold** and `code`.

- First item
- Second item

Translated (Spanish):

# Bienvenido

Este es un párrafo con **negrita** y `code`.

- Primer elemento
- Segundo elemento

Properties Files

Java-style properties files for JVM applications.

Format

# Comment (preserved)
greeting=Hello
farewell=Goodbye
message.with.dots=This works too

Handling Notes

• Comments are preserved
• Unicode escapes are handled correctly
• Line continuations are supported

XLIFF

XML Localization Interchange File Format for professional translation workflows.

Supported Versions

• XLIFF 1.2
• XLIFF 2.0
• XLIFF 2.1

Handling Notes

• Source/target structure is preserved
• Translation state attributes are updated
• Notes and comments are preserved
• Inline elements are handled correctly

PO/POT Files

GNU gettext format used by many frameworks including WordPress.

Format

#: src/app.js:15
msgid "Hello"
msgstr "Hola"

#: src/app.js:20
msgid "Goodbye"
msgstr "Adiós"

Handling Notes

• References and comments are preserved
• Plural forms are handled for supported languages
• Fuzzy flags can be set/cleared based on confidence
• Context (msgctxt) is considered during translation

Apple Strings

Localization format for iOS and macOS applications.

Format

/* Comment */
"greeting" = "Hello";
"farewell" = "Goodbye";

Handling Notes

• Comments are preserved
• String interpolation tokens (%@, %d, etc.) are protected

Placeholder Protection

Babelize automatically detects and protects common placeholder patterns:

File Size Limits

Encoding

All files must be UTF-8 encoded. Other encodings are converted automatically with a warning.

Unsupported Formats

The following formats are not currently supported:

• Microsoft Office documents (.docx, .xlsx)
• PDF files
• Binary formats
• Proprietary CAT tool formats

See our Public Roadmap for planned format additions.