This advanced customization i18n module has undergone significant improvements and changes since version 2.1.3 of Tencent Cloud Chat UIKit. This documentation introduces the usage of the new version, starting from version 2.1.3.
Please make sure that your project depends on a version of tencent_cloud_chat_uikit that is equal to or higher than 2.1.3.
English, Simplified Chinese, Traditional Chinese, Japanese and Korean have been embedded in Tencent Cloud Chat TUIKit as the default interface languages.
Adding other interface languages, modifying the current language entries or even adding new language entries are available for you, according to the instructions of this tutorial.
Utilizing the Default Languages
If your application solely requires Chinese (both traditional and simplified), English, Japanese, and Korean languages, and there is no need to modify translations or add new language entries, please refer to this section.
Choosing Device Language
No further steps are needed, as meeting device language can be automatically.
Pre-set the Language Manually
If you tend to specify the language manually, please provide the target language Enum to init() in TIMUIKitCore.getInstance().
import 'package:tim_ui_kit/tim_ui_kit.dart';
final CoreServicesImpl _coreInstance = TIMUIKitCore.getInstance();
final isInitSuccess = await _coreInstance.init(
language: LanguageEnum.en, // Enums as below
// ...Other configurations
);
Enum options for language：
enum LanguageEnum {
zhHant, // Chinese, traditional
zhHans, // Chinese, simplified
en, // English
ko, // korean
ja // Japanese
}
Modify Language Dynamically
Please just invoking I18nUtils(null, language);, while the language here should be set as the ISO 639 Language codes.
Example code:
I18nUtils(null, "en");
Utilizing the Advanced Customization Internationalization
For adding new extra languages beyond English, Simplified Chinese, Traditional Chinese, Japanese, and Korean, modifying specific translation items, or adding new language entries, please refer to this section.
Note
This solution only works for languages with a left-to-right reading direction. For small languages that read from right to left, such as Arabic, please fork our source code from our GitHub repository to complete the custom left and right mirroring Development adaptation, and import to your project manually.
Getting Started
Before using the Tencent Cloud Chat i18n Tool, you need to fork the package repository to your local machine and set up the package path in your project's pubspec.yaml file. Follow these steps:
Replace <your-username> with your GitHub username.
4. In your project's pubspec.yaml file, add the local path to your forked repository under the dependency_overrides section:
dependency_overrides:
tencent_chat_i18n_tool:
path: /path/to/your/local/repository
Replace /path/to/your/local/repository with the actual path to the cloned repository on your local machine.
Now you can use the Tencent Cloud Chat i18n Tool by running the main script in the root directory of your project.
(Optional) Adding New Entries in Your Project
To add new entries in your project, you need to wrap the entries using the following methods:
For entries without parameters, use the TIM_t("Entry") method. For example: TIM_t("Hello").
For entries with parameters, use the TIM_t_para("Template: {{option}}", "Template: $option")(option: option) method. TIM_t_para supports parameters from option1 to option10. For example: TIM_t_para("Server error: {{option8}}", "Server error: $option8")(option8: $option8) (where option8 is the parameter name).
Applying these methods in your project ensures that the entries are correctly handled with multi-language support.
The entries here can be in any language you specified. The following picture uses Chinese as a sample, but it is not limited to Chinese only.
Usage - Customization
Follow these steps to use the Tencent Cloud Chat i18n Tool:
1. Run the tool dart run tencent_chat_i18n_tool. By default, it will read the local package path specified in your project's pubspec.yaml file. If you want to use a different path, you can enter it when prompted.
2. Select option A (A. Add new language entries for internationalization. This action must be performed before adding new entries.) to add new language entries. The tool will provide two ways to add new entries:
Option 1 (1. Read new entries from the 'new_language_entries.txt' file in the project root directory.): Read new entries from the 'new_language_entries.txt' file in your project's root directory. You can manually add the entries you want to include in this file and then choose this option to add them to the tool.
Option 2 (2. Scan the project code to extract new entries and update the 'new_language_entries.txt' file (currently supports Simplified Chinese only).): Scan the project code to extract new entries and update the 'new_language_entries.txt' file (currently supports Chinese only). When you choose this option, the tool will automatically scan the specified directories (e.g., 'lib') in your Dart files and extract Chinese entries from them. Then, open the new_language_entries.txt file and review the extracted entries. If necessary, make any edits to the entries.
After editing the new entries scanned to new_language_entries.txt, press Enter to continue the process.
The process of this step is shown in the following pictures. Once finished, it will print the language pack JSON files that have been updated with the new entries.
3. Run the tool again and select option B. The tool will save the built-in language entries in JSON files to your project directory.
4. Open the JSON files located in the languages directory and translate the new entries at the bottom of each file. At this point, you can also locate specific entries by their key values and modify the translation text in each language entry library. However, please do not delete any entries that are not needed.
5. (Optional) If you want to add support for a new language, follow these steps:
Navigate to the languages directory in your project.
Choose a language file that you are familiar with and make a copy of it.
Rename the copied file to strings_${ISO_LANGUAGE_CODE}.i18n.json, where ${ISO_LANGUAGE_CODE} is the ISO code of the new language you want to add (e.g., strings_fr.i18n.json for French).
Translate all the entries in the new file to the corresponding language.
6. Run the tool again and select option C (C. Inject your modified language JSON files for all languages back into the tool, allowing the updated configuration to take effect.) to inject your modified language JSON files back into the tool. The updated configuration will now take effect in your project.
After completing these steps, the changes you made will be applied to the local copy of the Tencent Cloud Chat i18n Tool. If you want to collaborate with others or share your changes, you can push the modified package source code to your internal Pub server or Git repository. To use the updated package as a dependency in your project, simply update the package path in your pubspec.yaml file to point to the online repository:
Replace <your-username> with your GitHub username.
Now, you can re-run your project, and will find the customized language entries translation takes effect.
Choosing Display Language
Choosing device language
No further steps are needed, as meeting device language can be automatically.
Pre-set the language manually
If you tend to specify the language manually, please provide the ISO 639 Language Codes of the language to init() in TIMUIKitCore.getInstance().
import 'package:tim_ui_kit/tim_ui_kit.dart';
final CoreServicesImpl _coreInstance = TIMUIKitCore.getInstance();
final isInitSuccess = await _coreInstance.init(
extraLanguage: "ja", // ISO 639 Language Codes
// ...Other configurations
);
Modify language dynamically
Please just invoking I18nUtils(null, language);, while the language here should be set as the ISO 639 Language codes.
Example code:
I18nUtils(null, "en");
Update Instructions
The Tencent Cloud Chat i18n package will be updated synchronously with the Tencent Cloud Chat UIKit to maintain version consistency. With each update, we will add new entries from the latest version of Chat UIKit to this package. All updates will be published synchronously on pub.dev and the GitHub repository.
If you have forked this package to your GitHub account, please note that you need to synchronize the latest entry library of this package to your forked version via pull upstream operation whenever the Chat UIKit is updated. This ensures that your forked version contains both the entries you added or modified and the new entries we added with each version. When merging the code and resolving conflicts, please make sure that each JSON entry library remains intact.
If the merged JSON files cannot be used directly, you can follow the instructions in step 7 above to rerun the program and select option C to apply the updates. Please note that before executing option C, you need to ensure that each language entry JSON is complete and error-free.
Here's a step-by-step example of a pull upstream Git operation:
1. First, add the upstream remote repository to your local repository:
2. Fetch the latest changes from the upstream repository:
git fetch upstream
3. Switch your local repository to the branch you want to update (e.g., main or master):
git checkout main
4. Merge the changes from the upstream repository into your local repository:
git merge upstream/main
5. If there are any conflicts, resolve them in your editor, ensuring that each JSON entry library is intact.
6. Commit the changes after resolving conflicts:
gitadd.
git commit -m "Merge upstream changes and resolve conflicts"
7. Push the changes to your remote repository:
git push origin main
Now, your forked version includes the latest entry library. If you need to apply the updates, follow the instructions in step 7 above to rerun the program and select option C.
Appendix: Language codes
Language
Code
Language
Code
Arabic
ar
Bulgarian
bg
Croatian
hr
Czech
cs
Danish
da
German
de
Greek
el
English
en
Estonian
et
Spanish
es
Finnish
fi
French
fr
Irish
ga
Hindi
hi
Hungarian
hu
Hebrew
he
Italian
it
Japanese
ja
Korean
ko
Latvian
lv
Lithuanian
lt
Dutch
nl
Norwegian
no
Polish
pl
Portuguese
pt
Swedish
sv
Romanian
ro
Russian
ru
Serbian
sr
Slovak
sk
Slovenian
sl
Thai
th
Turkish
tr
Ukrainian
uk
Chinese (Simplified)）
zh-Hans
Chinese (Traditional)
zh-Hant
Contact us
If there's anything unclear or you have more ideas, feel free to contact us!
Yes
No
Was this page helpful?