Migrating Existing Translations to the Cloud

Hey Developers,

In Introducing the Cloud Localization Tool Suite Post, we announced our new suite of cloud localization tools to help you translate your games and share your content with players worldwide.

In this post, you can find information on how to:

  • Understand the differences between the old embedded localization tables and the new cloud localization table
  • Upload and download your cloud localization table data using the Localization Tools Studio plug-in for offline/local editing and translation management
  • Migrate your existing Studio-based/embedded localization tables to the cloud

Embedded Localization Tables vs. Cloud Localization Tables

The new cloud localization tools keep your localization data in web/cloud-based localization tables.

Here are the key differences for you to understand
Embedded Loc Table (Current) Cloud Loc Table (New)
Local, Studio-based Web/Cloud-based
Place-based, can have multiple tables per place
Updating localization requires publishing the game Updates to localization are (almost) instantaneously live and do not require publishing your game.
Add source text via Studio-based Text Scraper, manual input, or custom scripts Add source text with player-driven, client-side Automatic Text Capture or CSV upload
Edit translations in CSV file Edit translations in web-based localization editor or CSV (offline)
Managed via the Export/Import buttons in the Studio plugin Managed via the Upload/Download buttons in the Studio Plugin
Supports additional languages Only allows Roblox-supported languages to be uploaded
Uses language-locale codes (es-es, pt-br, de-de, fr-fr) Uses language-only codes (es, pt, de, fr)

Uploading and downloading your cloud localization data

With the release of the cloud localization tools, we have updated the Localization Tools Studio plug-in to allow you to upload and download your cloud localization table via CSV (Comma-Separated Values) file from within Studio.

To find these new options, open up the Plugins Tab > Localization > Tools. You’ll see a new section in the Localization Tools plugin panel called Game Localization Table with options to Upload and Download CSV content:

Note: Since the cloud localization tables are web-based, these options are only available for published games. You’ll need to publish your game first for these controls to appear.

Migrating your existing translations to the cloud

If you have existing translations that you created using the Studio-based tools, you’ll need to do the following to migrate your translations to the cloud localization table.

  1. If you have multiple Localization Tables, consolidate them into one single Localization Table.

    • Using the Localization Tools Studio plugin, export the Localization Tables for your game.
    • Use Excel or Google Sheets to consolidate all the entries in one Localization Table.
  2. Eliminate duplicate entries from the Localization Table.

    • A duplicate entry is one where both Source/Context are the same or where the unique key is the same.
    • It is not a duplicate entry if the Context is different, but the Source is the same.
  3. Check that your Localization Table references language-only locale codes (e.g. en, es, pt, fr) instead of language-country locale codes (e.g. en-us, es-es, etc.) for the translation column headers

  4. (Optional) Perform some housekeeping on your Localization Table to help translators. These are optional suggestions, but will help result in better translations for your game.

    • Check your Localization Tables to make sure that any parameters in your Source Text is properly denoted with curly brackets (Reference: Format Strings)
    • Provide notes for the translators in the Examples column to help with any game- or Roblox-specific terms, meme references, or anything else that translators may have trouble translating off the bat.
  5. Upload your consolidated localization table to the cloud using the Localization Tools Studio plugin (see instructions below).

Uploading a CSV file to your cloud localization table

The Game Localization Table uploader accepts CSV files with the following format:

To understand the Key, Context, Example, and Source fields, take a look at this troubleshooting article.

  • Only Source or Key are required for an entry in the localization table. Context and Example are optional, but help translators provide more accurate translations for your Source text.
  • Note: only supported Roblox platform languages (currently: en, es, pt, fr, de, ko, zh-hans, and zh-hant) can be uploaded to the cloud localization table. More languages are coming soon!

The upload will give you a summary of changes to the Game Localization Table. Once you select “Confirm,” your new table will be uploaded to the cloud and your game will be localized.

A few things to keep in mind
  • If the Key, Context, and Source for an entry in your CSV file matches exactly the Key, Context, and Source for an existing entry in the cloud localization table, the uploader will recognize this as a Change. The data for that entry in your CSV file will completely replace the data for the matching entry in the cloud localization table - the uploader does not merge the CSV entry with the cloud entry!
    • Example: You have a CSV file with the French translations for your game, and another CSV file with the German translations. If you upload the French CSV file and then upload the German CSV file, the result is that only the German translations will be in your cloud localization table. The French translations will be overwritten to blank values when you upload the German CSV file.
  • If you have existing translations for a supported locale and notice that the uploader is warning you about unsupported locales, check to make sure that your CSV file is using language-only codes (es for Spanish; pt for Brazilian Portuguese/Portuguese; de for German; fr for French; ko for Korean; zh-hans for Simplified Chinese; zh-hant for Traditional Chinese). This is different from the previous embedded localization tables!

Important note:

  • Cloud LTs will be instantly live with no review/approval process at this time. Please keep this in mind when publishing translations to live games.

FAQ

Q: If I upload my own localization table through Studio, what happens to the cloud stored localization table?

A: Content from your uploaded table will replace the content in the cloud so you can stay in control. However, we don’t currently have any versioning support so be careful when you do this or you might lose translations.

Q: Can I use a hybrid of embedded and cloud Localization Tables?

A: Yes, you can use embedded place-based Localization Tables simultaneously with the cloud localization table. If an entry exists in both tables, data in the embedded table takes precedence over data in the cloud localization table. If the translation for an entry is missing from the embedded table, auto-translation and API-based lookup will ‘fall through’ to the cloud localization data.

Q: How can I add translations for languages that Roblox does not yet support?

A: You can only upload languages into the cloud table that Roblox currently supports. If you want to provide translations for languages that Roblox doesn’t support, you can use an embedded localization table. However, this approach requires getting the player’s locale from SystemLocaleId to retrieve translations, which we don’t recommend.

Q: I currently use `LocalizationTable:GetTranslator(localeId)` to get a locale-specific Translator. Is there an equivalent function that works with the cloud localization table?

A: Yes! Currently, LocalizationTable.GetTranslator(localeId) retrieves a Translator that only has embedded localization table data. Use LocalizationTable.GetTranslatorAsync(localeId) to retrieve a Translator with both embedded and cloud localization table data.

Q: Will `LocalizationService.GetTranslatorForPlayer(player)` work with the new cloud localization tables?

A: No - GetTranslatorForPlayer(player) will return a Translator that only contains embedded localization table data and is now deprecated. Use GetTranslatorForPlayerAsync(player) instead. This will retrieve a Translator with both cloud localization data and embedded localization data.

  • GetTranslatorForPlayerAsync(player) will yield the Lua thread and should be called using pcall(), like other async methods.
  • GetTranslatorForPlayerAsync(player) will only return a Translator instance with cloud localization data if [Use Translated Content is enabled for your game](POST LINK).

Stay tuned for more awesome Localization Tools! If you have any questions or feedback, be sure to leave a comment on the Introducing the Cloud Localization Tool Suite.

3 Likes