Read Before Enabling Automatic Text Capture in Your Game

Updates Announcements
#1

Hello 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, we’re going to explain a bit more about the core text capturing functionalities.

The new Automatic Text Capture (ATC) feature is a convenient and easy way to gather the text in your game for translation. This post describes what the Automatic Text Capture tool is and describes a few simple steps you can take to ensure you get clean, translatable results from ATC.

What is Automatic Text Capture (ATC)?

The Studio-based text scraper allows you to capture source text in your game to create an embedded (e.g. local) Localization Table asset. The Studio-based text scraper has some limitations, though:

  • Requires you, the developer, to play through your entire game to capture all text, sometimes several times.
  • Only works in Play Solo mode - not very convenient for multiplayer games!
  • Captures text to a place-based embedded Localization Table

The new Automatic Text Capture tool is part of the suite of new cloud localization tools with several advantages over the Studio-based text scraper.

  • Client-side, player-driven text capture - quicker, more comprehensive coverage of all text in your game, captured as players just…play your game!
  • Works for both solo and multiplayer games
  • Captures text to the web-based cloud Localization Table for your game - one table for all places in your game’s universe.

Before you enable ATC for your game

  1. Disable AutoLocalize for certain GUI elements in your game to prevent Automatic Text Capture from filling your cloud localization table with playername-based entries or user-generated content (UGC).

    • Standalone UGC Content: Displaying a pet’s name above its head, such as “Fido”
    • Ephemeral/Temporary Content: Log messages, random codes (Server code: AS3KE), one-time messages that will not be shown again
How to disable AutoLocalize for a GUI element

Set the AutoLocalize property for that GUI element to false.

  • For example, if you are using a forked version of BubbleText to display chat messages from players in your game, you will want to add bubbleText.AutoLocalize = false to function this:CreateBubbleText(message) to prevent player chat messages from being captured by ATC.

  • Note: Disabling AutoLocalize for a GUI element will prevent both Automatic Text Capture and auto-translation for text in that element.

  1. Manually add parameterized entries to your CSV localization table for text containing the following:

    • Username of a currently non-playing user

      • Custom leaderboard
      • Custom friends’ list that shows online/offline friends

    • Embedded complex number format

      • Foreign number formats
      • Large numbers with separators (You have $1,390,840.34)

    • Embedded date and/or time

      • It is 1/7/2019.
      • The time is 1:45PM.

    • Embedded user-generated content (UGC)

      • Pet or house name (Pet name: Fido; new_storm's Base)

    • Dynamic content within a string

      • Do you want to buy a sword?
      • May new_storm join your team?
      • Server code: AS3KE
How to add parameterized entries to your CSV localization tables

To understand how to format parameters in your text, check out the format strings article on the Developer Hub.

  1. Create an empty Localization Table CSV file.

    • You can create a comma-separated values (.CSV) file either in a text editor or a spreadsheet editor like Excel/Google Sheets.

    • The CSV file should contain the following when opened in a text editor:
      Key,Context,Examples,Source

  2. Add an entry for any text in your game that fits one of the above scenarios.

    • An entry is a row in your localization table with Key, Context, Example, Source values.

    • An entry must have EITHER a unique Key value OR a unique Source value.

    • Context and Example are optional fields.

      • Context refers to the GUI element that source text appears in. You can use this to specify Context-specific translations.

      • Example allows you to add notes and references for your human translators.

  3. Use the Localization Tools Studio plugin to upload the CSV file containing your parameterized entries to your game’s cloud localization table.

    03_ImportExport
    03_ImportExport461×709 35.4 KB

Parameterized entries examples
Situation Original text Parameterized string
Username of a currently non-playing user Global Leaderboard 1st Place: new_storm Global Leaderboard 1st Place: {playername}
May Player1 join your team? May {playername} join your team? (for asynchronous requests)
Embedded complex number format, such as foreign number formats or large numbers with separators You have $1,390,840.34 You have ${1:num}
Embedded date It is 1/7/2019 It is {1:shortdate}
Embedded user-generated content (UGC), such as a pet name Pet name: Fido Pet name: {1}
(Optional) Dynamic content within a string Do you want to buy a sword? Do you want to buy a {1}? [See Note-1 below]
Server code: AS3KE Server code: {1}
(Dynamic Content) If you’re listing a set number of players in a string, with optional additional parameterized content: Winners: 1st place: new_storm with 35 points, 2nd place: Nightgaladeld with 27 points, 3rd place: jparty with 25 points "Winners: 1st place: {1} with {2} points, 2nd place: {3} with {4} points, 3rd place: {5} with {6} points" [See Note-2 and Note-3 below]
(Dynamic Content) If you’re listing a variable number of players in a string, without additional parameterized content: Survivors: new_storm, Nightgaladeld, jparty Survivors: {list} [See Note-3 below]

  • Note-1: Do not recommend this approach, as gender of objects may affect the translation of the entire sentence.

  • Note-2: The text must be enclosed in double quotes because it contains commas. If you do not include the quotes, the Studio upload tool will throw an error when you try to upload the CSV file, as the CSV format will read the commas in the sentence as separators.

  • Note-3: Named ({parametername}) and numeric ({1}) parameters cannot both be used in the same string

    • Valid string formatting:

      • {playername} has obtained {numItem} {itemname}
      • {1} has obtained {2}

    • Invalid string formatting - will generate error when trying to upload CSV via Studio plug

      • {playername} has obtained {1} {itemname}!

  • Note-4: Requires using API (Translator.FormatByKey(key,args)) to retrieve translation. You will need to generate and supply the list of players as the parameter for this string. (Reference: API:Class/Translator)

What to do if you need the parameter in a formatted string to be translated

Scenario

  • If you are using a parameterized string, such as {playername} found {itemname}!; AND
  • You are using auto-translation, instead of a key-based lookup; AND
  • One of the parameters is something that needs to be translated; THEN

You will need to add the :translate specifier to that parameter.

  • Without the :translate specifier:

    {itemname}: R${itemcost} → Steel Sword: R$100

  • With the :translate specifier:

    {itemname:translate}: R${itemcost:int} → La Espada de Acero: R$100


Clearing the Cloud Localization Table

If you need to clear your cloud localization table at any point, upload an empty or clean localization table via the Localization Tools Studio plug-in panel.

  • An empty localization table is just a .CSV file containing Key,Context,Examples,Source.
    1. Open a text file.
    2. Paste in Key,Context,Examples,Source.
    3. Save as LocalizationTable.csv.

  • A clean localization table is a .CSV file containing existing source/translation data that you created using the Studio-based text scraper, manual input, or custom scripts.


FAQ

Q: Auto-scraping only scrapes live text in the production game - how can developers translate strings in future updates before they go live?

A: You do not need to use Automatic Text Capture to add source text to your cloud localization table. If you download your cloud localization table via the Localization Tools Studio plug-in, you can add entries for upcoming updates through manual input, the Studio text scraper , or your own custom scripts.

Q: I develop in one universe and have my main game in another universe. Can I directly copy the cloud localization table from my development universe to the main universe?

A: At this time, there is no way to directly share or push the cloud localization table from one universe to another. You will need to use the Localization Tools Studio plugin to download the table from your development universe and upload it to your main universe.

Happy translating! Let us know how the tools are working and give us feedback on the Introducing the Cloud Localization Tool Suite post.

1 Like
Introducing the Cloud Localization Tool Suite
#2
#3