LocalizationPyTools

What is LocPyTools and why to use it

Imagine you set up all localizable texts in your Unreal project and now you want to send them over to the localization company for translation process. However, the localization company of your choice doesn't want to work with PO files provided by Unreal; they want XLSX files instead.

Here comes the LocPyTools - this python program provides a set of tools that automatize generating a XLSX file with missing translations and rewrites Unreal PO files with translations read from existing XLSX documments.

Basic assumptions

Before using LocPyTools you need to learn about some basic assumptions takes during developing this program:

• all string tables used in UE project are created from data loaded from CSV files
• all localization data have been exported from UE built-in Localization system to a bunch of PO files
• the translation company of your choice uses only with XLSX files for texts translation
• texts IDs in XLSX files are composed with CSV file name and text key used in UE separated by the '+' sign: eg.: 'ST_SomeFile.csv+Some_Text_ID'

Installation and usage

LocPyTools was developed and tested with Python 3.10. All source scripts can be found in LocalizationPyTools directory on this repository.

You can either run locpytools.py script from LocalizationPyTool/Source directory on your own or use provided executable file available in LocalizationPyTools/dist directory.

The UETestProject directory contains an example project created in Unreal Engine, while the XlsxTranslations directory holds some translations for texts found in this project. Feel free to play with it and learn how to use the LocPyTools program.

Support

In case of any questions you can contact me at sosnowska.kk@gmail.com.

License

This project is licensed under the MIT License. Learn more

LocPyTools Manual

Following paragraphs contain descriptions of all commands available in LocPyTools program.

The -h, -help commands

It prints a short manual for the program.

The quit command

It quits the program.

The mkconfig command

It generates the .config file used by other tools. Note that this file is automatically generated at the start of the program if none .config file has been found.

The xlsxan command

It runs the analyser tool for all XLSX files found in input directory. The result of this analysis is a dictionary with all translations for each found native text. All input arguments are read from config file (xlsxan prefix).

Usage

1. Run locpytools program. Make sure that the .config file exists - if not, you can generate one using the mkconfig command.
2. Make sure the .config file has proper data for arguments with prefix xlsxan.
3. Run xlsxan command in locpytools program.

The lmt command

It runs the listmissingtexts tool, which generates a new XLSX file with all missing translations.

First, it analyses all XLSX files with translations and register all translations in a dedicated dictionary. For this step, the xlsxan tool is used.

After that, the program goes through all input CSV files (those files are used to create string tables used in UE project) and read their content. Each text ID from CSV file that is not in generated translations dictionary is written down into output XLSX file. As a result, the output XLSX file will contain all texts that are missing their translations.

Usage

1. Run locpytools program. Make sure that the .config file exists - if not, you can generate one using the mkconfig command.
2. Make sure the .config file has proper data for arguments with prefixes xlsxan and lmt.
3. Run lmt command in locpytools program.
4. New MissingTexts_XYZ.xlsx file should be generated inside the path provided for lmt_xlsx_output_dir argument. The XYZ in the file name will be replaced with a date and time of the file creation.

IMPORTANT NOTE ABOUT lmt TOOL

The lmt tool demands CSV files to be formatted with serveral rules, which are the following:

• in each row the cells are separated with , character
• each cell must be encapsulated within quotation characters "
• each text entry is contained in only one line. If you do need to create multi-line text, use \r\n formatting tag to create new line entry inside the source text
• do not leave empty rows inside CSV file, as Unreal's Localization system might be not able to gather texts from such file

How BAD formatting looks like:

Key,SourceString,Comments
,,,
animal_cat,cat,A cat
,,,
animal_dog,dog,A dog
,,,
animal_cat_multiline,"This
is
THE CAT",A multi-line cat"
,,,
,,,
,,,

And now how GOOD formatting looks like:

"Key","SourceString","Comments"

"animal_cat","cat","A cat"

"animal_dog","dog","A dog"

"animal_cat_multiline","This\r\nis\r\nTHE CAT",The multi-line cat"

The lct command

It runs the listchangedtexts tool, which generates a new XLSX file with all source texts, that have been changed and may have outdated translations. Generally, this program helps to find all source texts, whose new meaning is completely different from the previous version, which invalidate their existing translations.

This simple program analyses data from the input PO file with native culture. It compares the content of the msgstr and the msgid parts of the localized text data. If msgstr text is different than the text assigned to msgid, it means that the source text in msgid has changed, and the existing translation stored in msgstr property may be outdated.

Usage

1. Open your project in Unreal editor, go to the Localization Dashboard window and use Gather texts option to update localized texts archives in your project.
2. Run locpytools program. Make sure that the .config file exists - if not, you can generate one using the mkconfig command.
3. Make sure the .config file has proper data for arguments with lct prefix.
4. Run lct command in locpytools program.
5. New ChangedTexts_XYZ.xlsx file should be generated inside the path provided for lct_xlsx_output_dir argument. The XYZ in the file name will be replaced with a date and time of the file creation.

The xlsxreg command

It runs the xlsxregistry tool, which merges all texts entries from existing XLSX files with texts translations. The main purpose for this program is to speed up the process of looking for a particular text translations in order to update or remove them.

The generated XLSX registry provides following information for each localized text:

• ID - the text unique key
• Source Text - the native text
• Context - additional information for translators
• Text Source File - name of the file where the text is defined
• TTranslations Batch - name of the file where we can find all translations for this text

Usage

1. Run locpytools program. Make sure that the .config file exists - if not, you can generate one using the mkconfig command.
2. Make sure the .config file has proper data for arguments with xlsxreg prefix.
3. Run xlsxreg command in locpytools program.
4. New TranslationsRegistry_XYZ.xlsx file should be generated inside the path provided for xlsxreg_output_dir argument. The XYZ in the file name will be replaced with a date and time of the file creation.

The pou command

It runs the poupdater tool, that updates existing PO files with provided texts translations found in XLSX files.

First, it analyses all XLSX files with translations and register all translations in a dedicated dictionary. For this step, the xlsxan tool is used.

After that, it goes through all input PO files (those are set of texts for all cultures used in UE project) found inside subdirectories of input directory and read their content. For each text ID msgctxt that has existing translations in generated translations dictionary its assigned translation text msgstr is replaced by updated translation from generated translations dictionary.

Usage

1. Open your project in Unreal editor and go to the Localization Dashboard window. Use the Export texts option available under Cultures tab to generate a PO file for all cultures (you can also export texts to PO for each culture separatedly).
2. Run locpytools program. Make sure that the .config file exists - if not, you can generate one using the mkconfig command.
3. Make sure the .config file has proper data for arguments with prefixes xlsxan and pou.
4. Run pou command in locpytools program.
5. At this point, all PO files inside the directory path provided for pou_po_source_dir have been updated with the existing translations loaded from XLSX files.
6. Go back to the Localization Dashboard in the Unreal editor and use the Import texts option available under Cultures tab to load new translations for all cultures from updated PO files (you can also import texts from PO for each culture separatedly).