Using the Unreal Engine 4 localization with Coherent UI
Hi there, I am Stan and today I will show you how to use the Localization feature of Unreal Engine 4 with the Coherent UI. Usually there are many hassles when it comes to localizing a game, but when using UE4 this is not the case. Epic has done a great job with their new Localization System, which was scrapped and rewritten during the UE3->UE4 transition. It is still in development, but I can see the effort that was put into designing the system.
The localization workflow will be as follows:
- Declare the Text in the HTML UI that will be translated.
- Generate Translation manifest and archive files.
- Enter the translation strings for texts that are to be translated.
- Generate translation manifest and archive files again to rebuild the binary localization file.
- Change engine’s current culture and do the C++/HTML binding.
To demonstrate how the localization system works, I will use a very simple sample – the Menu_Map that ships with the Coherent UI installer for UE4. It is a simple level that shows a menu with 3 buttons, which we would like be translated.
Step 1 – Declaring strings that will be translated.
In this step I will tag the buttons that will have their text translated in the HTML and declare that I want translation for a text entry.
The Menu map loads the coui://UIResources/Menu/menu.html page, which will be our starting point.
In the page you can find some css includes, javascript includes and most importantly – the 3 menu buttons. In the button tag of the start button I will add a property called data-l10n and set its key to StartButton. E.g.
|
1 2 |
<button id="play" class="btn btn-large btn-primary" type="button" data-l10n="StartButton">Play</button> |
The name of the “data-l10n” tag can be anything you would like, as long as it starts with “data-“.
Now we have to declare that we want a translation for the “StartButton” key. In the menu.html file I will add a comment containing the following declaration:
|
1 2 3 |
<!-- NSLOCTEXT("MenuNamespace", "StartButton", "StartButton translation in every language") --> |
It shouldn’t matter where in the HTML page the comment is, in my case I placed it right after the Doctype HTML declaration. Now, what is this C++ like declaration and why we need it?
NSLOCTEXT is a C++ macro that declares a new localization text. It takes 3 parameters:
- Localization Namespace – it allows localization texts to be grouped together, and thus allow easier bookkeeping – e.g. all button names can be in the “MenuNamespace”
- Key – unique identifier for a namespace, used together with a namespace to identify a localized text entry
- Text Literal – the text literal is a sample text that is used to describe the key. If a translation for the current Culture is not found, the Text Literal will be used instead.
Step 2 – Generate translation manifest and archive files.
The UE4 localization system works with three types of files:
- .manifest – contains json code describing Namespaces, Keys, Text Literals and the file/line where the localized text is. Most probably they are used to generate .archive files.
- .archive – it has a very similar structure to .manifest file, but instead of the location of the localized text, it contains the translation of the localized text for a specific language.
- .locres – a binary file that contains the binary representation of the localized texts for a specific language. The UE4 localization system can only read from .locres files.
Now, back to the practical part. The generation of the manifest, archive and locres files happens with the help of a Unreal Engine commandlet called GatherText. Commandlets are mini-programs with a specific purpose. In this case the commandlet reads a configuration file and executes the steps defined in it. The commandlet is called with:
|
1 |
PathToEditor/Editor.exe PathToGame/Game.uproject -run=GatherText -config=PathToConfig/Config.ini |
or in my case:
|
1 2 |
F:3_UEunrealEngineUE4EngineBinariesWin64UE4Editor.exe F:3_UEunrealCoUITestFPSCoUITestFPS.uproject -run=GatherText -config="F:3_UEunrealCoUITestFPSConfigLocSettings.ini" -log > localization.log |
Note: The -log > localization.log bit is optional and is used to generate a localization.log file. The log will be created in your current working directory and will contain the output log of the GatherText commandlet. If something goes wrong, you can check in the log what and where.
The configuration LocSettings.ini file contains a list of settings and series of steps that will be executed by the GatherText commandlet. The config that I have used is the following:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 |
[CommonSettings] SourcePath=F:/3_UE/unreal/CoUITestFPS/Content/Localization/Game DestinationPath=F:/3_UE/unreal/CoUITestFPS/Content/Localization/Game ManifestName=LocalizedText.manifest ArchiveName=LocalizedText.archive SourceCulture=en CulturesToGenerate=en CulturesToGenerate=es ;Get all FTexts from source code [GatherTextStep0] CommandletClass=GatherTextFromSource IncludePaths=../../CoUITestFPS/Source/CoUITestFPS/ IncludePaths=../../CoUITestFPS/UIResources ;File extensions that will be parsed SourceFileSearchFilters=*.cpp SourceFileSearchFilters=*.h SourceFileSearchFilters=*.html ;Generate Manifest [GatherTextStep1] CommandletClass=GenerateGatherManifest DestinationPath=F:/3_UE/unreal/CoUITestFPS/Content/Localization/Game ;Generate Archives [GatherTextStep2] CommandletClass=GenerateGatherArchive bPurgeOldEmptyEntries=true ;Generate Localized Text Resource [GatherTextStep3] CommandletClass=GenerateTextLocalizationResource ResourceName=LocalizedText.locres |
Most of the options in the configuration file are self-explanatory, but there are some things which I would like to point out:
CulturesToGenerate=enandCulturesToGenerate=es– used to generate English and Spanish localizations. For every language/locale you want to have a localization, you must add a row there with the language/region code.SourceFileSearchFilters=*.html– used to tell the parser to look inside .html files.SourcePathandDestinationPathpointing toF:/3_UE/unreal/CoUITestFPS/Content/Localization/Game– this is a default path used to find .locres files by the engine. If your files are in it, they should be automatically loaded by the engine.- The search filters for this samples are set to .h, .cpp, .html.
Step 3 – Enter the translation strings for texts that you want to translate.
After you have run the commandlet, in
|
1 |
YourGame/Content/Localization/Game |
you should have the following folder structure:
Now we would like to translate the key for StartButton (from section 1) in Spanish. In order to do so, navigate to the YourGame/Content/Localization/Game/es and open the LocalizedText.archive. In the “Translation” field you should enter the translation of Start Button in Spanish (I will trust google translate this time).
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 |
"Subnamespaces": [ { "Namespace": "MenuNamespace", "Children": [ { "Source": { "Text": "StartButton Translation in every language" }, "Translation": { "Text": "Botón de Inicio" } } ] }, |
Step 4 – Generate translation manifest and archive files again.
After we have filled the empty translation fields, we have to run the same commandlet again:
|
1 |
F:3_UEunrealEngineUE4EngineBinariesWin64UE4Editor.exe F:3_UEunrealCoUITestFPSCoUITestFPS.uproject -run=GatherText -config="F:3_UEunrealCoUITestFPSConfigLocSettings.ini" -log > loc.log |
Once the translation strings are filled, re-running the commandlet will not erase the existing translation entries and will re-generate the binary .locres file. If you are not sure if the Spanish translation made it to the .locres file, you can open the YourGame/Content/Localization/Game/es/LocalizedText.locres file with hex editor and inspect its contents.
Step 5 – Change engine’s current culture and do the C++/HTML binding
After we have generated the locres files with the localized tests it is time to head to the UI again and bind it to the game.
HTML
In the Menu.html page we have to ask the UE4 engine about the localization of the buttons tagged with “data-l10n” attribute. To do that, I have written a small script and put it right before the end of the HTML body:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 |
function SetLocalization(BtnNames) { var buttons = document.querySelectorAll('[data-l10n]'); for(var i = 0; i<buttons.length; ++i) { if(BtnNames[i] != "") { buttons[i].value=BtnNames[i]; buttons[i].innerText=BtnNames[i]; } } var wrapper = document.getElementById("buttons_wrapper"); wrapper.style.display="block"; } engine.on('SetLocalization', function (BtnNames) { SetLocalization(BtnNames); }); var locStrings = []; var texts = document.querySelectorAll('[data-l10n]'); for(var i = 0; i<texts .length; ++i) { locStrings.push(texts[i].dataset.l10n); } engine.on('Ready', function() { engine.call('GetTranslation', 'MenuNamespace', locStrings); }); |
The script does a few things:
- It selects every element with the data-l10n tag and puts the keys to be translated into an array.
- When the Coherent UI View loads and is ready, the script will call GetTranslation method in C++
- Binds the SetLocalization function to be called from C++
Note: Initially, the buttons are marked as hidden and when the SetLocalization event is received they are shown. This is done to prevent any text “flickering” that might occur, although my tests did not result in such.
C++
There are four things to do in order to make the localization work:
- Add a method that will check for translations of the keys from Javascriptvoid ACoUITestFPSMenuHUD::GetTranslation(FString Namespace, TArray Keys). You should include the following headers to your file in order to tell the Coherent UI binder how to bind the UE array and string types.
123#include "Coherent/UI/Binding/EventHandler.h"#include "CoherentFStringBinder.h"#include "CoherentTArrayBinder.h"
123456789101112131415161718void ACoUITestFPSMenuHUD::GetTranslation(FString Namespace, TArray<FString> Keys){TArray TranslatedButtons;for (UINT8 i = 0; i < Keys.Num(); ++i){FText MenuText;if (FText::FindText(Namespace, Keys[i], MenuText)){TranslatedButtons.Push(MenuText.ToString());}else{//There is no translation for this FText, this should not happen.TranslatedButtons.Push("");}}CoherentUIHUD->GetView()->TriggerEvent("SetLocalization", TranslatedButtons);}
- In the ACoUITestFPSMenuHUD::BindUI method of the MenuHud bind the GetTranslation method
123CoherentUIHUD->GetView()->BindCall("GetTranslation",Coherent::UI::MakeHandler(this, &ACoUITestFPSMenuHUD::GetTranslation)); - Change / Check current culture. I have put the set culture command in the CreateView() method of the HUD. With our current setup it is important that the culture is set before the view is created. Of course, you can change languages dynamically and the UI Text can be changed accordingly, but I wanted to cover just the most common case.
123auto CurrentCulture = FInternationalization::Get().GetCurrentCulture();FInternationalization::Get().SetCurrentCulture("es");
Note: If you don’t want to recompile your project every time for every localization, you can add the -culture=”DesiredCulture” in the command line of the game
- Finally, add -game command line parameter when starting your project. The localization system works only with standalone games so you have to run the game as a standalone, without the editor.
Now when you run the game, the menu buttons should be in Spanish.
This is everything you need in order to use the localization system of Unreal Engine. It came up quite lengthy, but I wanted to compile everything in one place, as it took me some time get the pieces of information available on the topic together.
What is your experience with other localization systems than the UE4 Localization system? We can discuss it in our forum
