Internationalization (i18n)

Charon supports localization by enabling text data to be stored in multiple languages using the Localized Text data type. This allows game data to be exported for translation, modified externally, and imported back after localization.

Supported export formats include XLSX, XLIFF (XML Localization Interchange File Format) and JSON. These formats are suitable for translation workflows involving external tools or localization teams.

Overview

Localization workflows in Charon rely on identifying fields of type Localized Text and processing them through either spreadsheet or industry-standard interchange formats. Translated data can then be re-integrated using import commands.

Common use cases include:

  • Managing multi-language game content.

  • Sending text data to third-party localization vendors.

  • Automating translation pipelines with CLI tools.

Supported Languages

Translation languages are defined in the Project Settings. To view the configured languages via the CLI, run:

charon DATA I18N LANGUAGES --dataBase gamedata.json

Exporting Translatable Text

Charon provides two primary formats for exporting localizable content: XLSX and XLIFF. Exporting can be done via the graphical interface or command-line interface.

XLSX Export (Spreadsheet)

The following example exports all translatable text to an Excel spreadsheet:

charon DATA EXPORT --dataBase "gamedata.json" --properties [LocalizedText] --output "text_all_languages.xlsx" --outputFormat xlsx

Key parameters:

  • --properties [LocalizedText]: Filters exported data to include only LocalizedText fields.

  • --languages: (Optional) Specifies which languages to include in the export.

Note

The exported spreadsheet may contain additional metadata columns that are required for correct import.

XLIFF Export (Industry Standard)

To export translation data in XLIFF format:

charon DATA I18N EXPORT --dataBase "gamedata.json" --sourceLanguage en --targetLanguage fr --output "en_fr_texts.xliff" --outputFormat xliff

Key parameters:

  • --sourceLanguage: Language of the original text.

  • --targetLanguage: Language to which the content will be translated.

  • --outputFormat: Format of the exported file. Supported values include xliff, xliff1, and xliff2.

Importing Translated Data

After translation, the modified data can be imported back into the project. Both XLSX and XLIFF formats are supported.

XLSX Import

To import translated spreadsheet data:

charon DATA IMPORT --dataBase "gamedata.json" --input "text_all_languages.xlsx" --inputFormat xlsx --mode safeUpdate

Key parameters:

  • --inputFormat xlsx: Indicates the input file format.

  • --mode safeUpdate: Ensures only existing fields are updated, without creating or deleting data.

XLIFF Import

To import translated XLIFF content:

charon DATA I18N IMPORT --dataBase "gamedata.json" --input "en_fr_texts.xliff"

Best Practices

  • Use XLSX when working with translators familiar with spreadsheet tools.

  • Use XLIFF for integration with professional translation software or localization platforms.

  • Validate the translated data with a dry run before importing changes into production data.

Working with Translation Teams

The standard human-translation workflow with Charon:

  1. Designers fill the primary language (e.g. English) for all content.

  2. Export XLIFF for each target language:

    charon DATA I18N EXPORT \
    --dataBase "gamedata.json" \
    --sourceLanguage en --targetLanguage fr \
    --output en_fr.xliff --outputFormat xliff

  3. Send the .xliff file to your localization vendor or translation management system (Crowdin, Lokalise, POEditor, or any XLIFF-compatible tool).

  4. Receive the translated file back from the vendor.

  5. Import the completed translation:

    charon DATA I18N IMPORT \
    --dataBase "gamedata.json" \
    --input en_fr_translated.xliff

  6. Repeat for each target language. CI/CD scripts can automate steps 2 and 5 for continuous localization pipelines.

Machine Translation

The cloud and server editions optionally integrate a machine translation service (e.g. Google Translate) to pre-populate target language fields as a first draft for translators to review. This speeds up the initial pass for teams with large amounts of text but does not replace professional translation for final copy.

Machine translation is configured per-server by an Administrator. When enabled, a Translate button appears on LocalizedText fields in the editor. Translated text is inserted as a draft — it must be reviewed and approved before the document is saved.

For studios without machine translation access, or for bulk text, the export/import workflow described above is the recommended path for all target languages.

Unsupported Formats

While Charon may accept other serialization formats (e.g., BSON, MsgPack), compatibility for internationalization workflows is only guaranteed for XLSX, XLIFF and JSON.

Additional Resources