Open Shirley-yhm opened 1 year ago
We've had some discussions in https://github.com/o3de/o3de/discussions/14287
Awesome feature, thanks for the rfc! An option for terminology that doesn't translate well is to just not translate that particular item until an appropriate translation is determined. Many products follow this model.
Ideally I would want to see testing against at least 3 languages (english, chinese, and ???) but understand that may not be feasible. Also, there will be considerations for button sizing and alignment in the editor. Example german is known for long translations, japanese fonts tend to be taller. We will also need to test what kind of performance and memory impact this will have.
I still think its a great idea to get the architecture in place and start making steps towards doing this. No reason not to start just because the road is long.
The only point I'd like to try to make here is that we have a bunch of code that isn't necessarily based on Qt and still emits english errors and other text (such as the runtime, other tools potentially, python scripts). in which case we'd need to think of whether we want a separate mechanism for translating those, since putting Qt in them would probably not be okay from a license (GPL-3 vs Apache) situation.
Its possible we could still use the same tags and macros, tooling (Lupdate, qt linguist) but use them without linking to qt.
Thanks for your feedback :)
Test against at least 3 languages
UI adaptation
Performance and Memory impact
License of QT
I had some discussion with @yuyihsu, @bhanuja-s(from UX team) and @AMZN-daimini recently. Combined with the above in this RFC, here are some conclusion related.
What we can do in the long term:
What I will adjust in the PR of this RFC in the short term:
Should I edit this RFC directly? What should I do once the above 3 points are finished? Please let me know asap if there is any other suggestions. Thanks!
For the sake of future discussion, I put the main contents of our discussion here.
From: Sanghavi, Bhanuja
With the time (and steps) it takes to re-launch the Editor, users should ideally be provided with a solution that changes the language in the Editor. However, with that being a long-term goal, I believe there might be ways that we can improve this in the short-term.
- Users should be provided an option in the Installer to select a language. When the download and installation is complete, all the engine tools and windows should be in the new language.
- Users should be provided an option in Project Manager to select a language, rather than in the Editor – this way the changes are global and reflect across the different engine tools and windows (Project Manager, Editor, Asset Processor).
- In the short-term, if the Editor is open they should be well instructed to save open levels/files, and to then relaunch the Editor for these changes to be applied.
- In the long-term, we should display immediate changes in the UI to the new language. We should definitely avoid the use of tooltips to retranslate UI, and as you suggest in the short-term have a translate button temporarily, something similar to the image below. In the long-term, it seems essential to correctly handle language changes and present accurate information to the users.
From: Aimini, Danilo
I like the idea of picking the language early in the install / project management flow so we can set it before the Editor is started. I have a couple of technical notes related to Shirley’s questions:
- Regarding the ability to switch language at runtime, it is theoretically possible. It would be a matter of defining a signal/bus, and have the UI widgets displaying labels listen to it and trigger a re-translation whenever that event is fired. Designs generated via UI files automatically fill in a retranslateUi function that can be used for this, so it sounds like it’s something Qt endorses. In practice, though, we would have to check whether it would be possible to embed such a refresh system directly into the UI Library components, so that all tools using them would just inherit the functionality without having to add repeated code ad-hoc in each tool. I’m sure some legacy tools like TrackView or the Lua Editor will still need some ad-hoc changes, but it may save us some time with the rest of the Editor. It is definitely the kind of change that could be worked on in development behind a flag, so we can test it piece by piece and only enable it by default when it's complete.
- Regarding the tools/layout names being used in the backend code, I would guess it may still be possible to always use the English names in the backend as keys to the layout information, and only translate those keys in the instance they are displayed in the editor. I do agree that the underlying system should actually use a different key, to be fair, but a refactor of the entire system may increase the scope of the effort right now so I'd go for something less intrusive first, and maybe backlog a deeper re-architecture.
- Finally, regarding a possible third language, I should be able to kickstart an Italian translation if it can help with testing the functionality. I know a few community members of the Discord would likely be interested in contributing the rest of the translations over time so it sounds like an easy win, and could provide the rest of the community with the proper info to also work on other languages.
Summary:
This feature proposes to implement internationalization in O3DE to support other languages besides English on UI.
What is the relevance of this feature?
O3DE only supports English on UI currently, which is not so friendly to users from other countries. Especially for new users who had never done 3D product development before, support for their native language might help them start with O3DE and understand the terminologies more easily.
The proposed solution implements internationalization support in O3DE. After this work, developers only need to add a new language type and translate strings that have already been extracted to support any other language as they want.
Feature design description:
Mechanism of QT's internationalization support is used in this feature. The basic flow is as follows (Chinese translation for example).
Tag —— Tag all strings to be translated on UI in source code.
Extract —— Use
lupdate
in QT to extract tagged strings into translation files with .ts suffix.Directory Structure:
Information of the tagged string with file path and line number will be added into TS file.
Linguist
Tool in QT to translate tagged strings in translation files. Developers can also modify TS files directly.Compile —— Use
lrelease
in QT to compile the translation files with .qm suffix.Directory Structure:
qtbase
is added to locate translations for basic Qt modules, such as Qt Core, Qt GUI, Qt Network, and Qt WidgetsTechnical design description:
Internationalization with QT
Internationalization with QT supports most languages in use today, and and will work on all platforms as long as the system has fonts to render these writing systems installed.
Three tools in QT are used to generate translation files automatically:
Implementation in O3DE
Currently, some strings to be translated have been tagged using Object::tr(). Translators are loaded in EditorQtApplication::Initialize().
However, the current implementation only supports localization in Editor and Asset Browser, and strings not in subclasses of QObject can't be translated.
Step 1. Set Translators
Based on what has been done in O3DE, this proposal uses
m_translators
with typeQVector
to store translators.Step 2. Load & Unload Translators
Since the startup time of each process are actually different, translators are loaded in every module separately.
Common functions are defined in file
Translation.h
.Translators are loaded/unloaded in every module separately.
Step 3. Tag
There are three types of strings to translate:
tr()
.QObject::tr()
orSubclassOfQObject::tr()
. In particular, QT can't be used in code of runtime.QT_TRANSLATE_NOOP
macro.Step 4. Extract
Strings tagged are extracted into corresponding TS files automatically.
add_translation_module
in cmake file of every module.Step 5. Translate
TS files are in type of XML. Translations can be added manually or using
Qt Linguist
tool.<translation> </translation>
, and the type will be removed indicating that translation of this string has been finished.After translation, TS files will be simplified and compiled into QM files with suffix
.qm
automatically. QM files are fast compact versions of TS files.Step 6. Read
tr()
orObject::tr()
can be read straightly.Translations of strings tagged by
QT_TRANSLATE_NOOP
macro need to be called byQCoreApplication::translate()
.Language Setting
A new setting for language is also needed in
Editor Settings
for users to switch language. It's designed like the setting namedConsole Background
.Editor Settings
-General Editor Preferences
-General Settings
. Other languages will be added later.Work Plan
Tag strings
in Editor and Asset Processor.generate translation files
(TS and QM) automatically.Chinese
.load
the translation files at startup andunload
them at teardown.Editor Settings
.What are the advantages of the feature?
How will this be implemented or integrated into the O3DE environment?
CMake build files will be added in the first PR. No additional processing is required by developers.
How will users learn this feature?
Once this proposal is passed, documents will be provided for users and developers to learn this feature.
Are there any open questions?
QString str = tr("Loading level %1 ...").arg(levelName)
will be extracted and translated in TS file as:Potential User Experience Improvements
According to the user experience we have collected, there are two questions worth considered.
Editor needs to restart to change the display language currently. Since it takes a long time to launch Editor and Asset Processor, restarting may lead to poor user experience.
It's hard to translate some terminologies accurately for developers, and inappropriate translations may confuse users.
Some experiment has been done in this scenario: Add description in English into tooltips when the display language is set to Chinese. However, this may lead to overly long tooltips and poor user experience. This will also increase the burden on developers who add translations.
Both of the above two questions need UX design and technical support.
Title of window's name is used as the key to store its layout. When the display language changed, key of the window will also change and information of its layout will become invalid.