A set of tools to manipulate Paradox localization files particularly for translating
- Source: It refers to the source language of your translation
- Destination (shorten dest): It refers to the destination language of your translation
Example : If I translate from English to French, the source directory refers to the directory of English localisation files.
I recommend you to install a Python environment with poetry, conda, virtualenv or pipenv.
poetry install
For example with conda, download and install miniconda
Create a conda environment
conda create -n paradox_loc python=3.7.1
Activate the conda environment
activate paradox_loc
Install Levenshtein package (only needed for apply_diff_all)
conda install python-levenshtein==0.12.0
OR
pip install python-levenshtein==0.12.0
Install pandas package (only needed for extract_existing_translation)
pip install pandas
Install coverage tool (only need for contributing to the project)
pip install pytest coverage genbadge[all]
Copy the file coverage.bat in the folder .git/hooks/ and name it pre-commit (it is normal there is no .bat).
Install pre-commit (only need for contributing to the project)
pip install pre-commit
pre-commit install
Update the localization files of your source languages. It also copy in the parent of the target directory an extract of the source localization and all files in target_dir.
python src/update_source.py <source_dir> <target_dir> <source_lang>
Example to update the English files of the HoI4 mod Kaiserreich
python src/update_source.py <...>\Steam\steamapps\workshop\content\394360\1521695605 <...>\GitHub\Traduction-FR-Kaiserreich\Traduction-FR-Kaiserreich english
Update files to translate on Paratranz
Get your Paratranz API token in the settings tab of your Paratranz profile.
Get the Paratranz project id by open the project and see the number in the url.
python src/update_paratranz.py <token> <project_id> <loc_dir> <language>
Example to update the RICE project (translation from English) on Paratranz
python src/update_paratranz.py <token> 2617 <...>\GitHub\RICE-for-CK3\RICE\localization english
To compile the code, run the following command
python compile_update_paratranz.py build
then put the dist/ directory in update_paratranz/
Download translated files from Paratranz
Get your Paratranz API token in the settings tab of your Paratranz profile.
Get the Paratranz project id by open the project and see the number in the url.
python src/download_paratranz.py <token> <project_id> <raw_dir_path> <utf8_dir_path>
Add in the destination files the lines which are missing from the source ones
python src/add_missing_lines.py <source_dir> <dest_dir>
Example to add in French files missing lines from English files
python src/add_missing_lines.py "<...>\game\localization\english" "<...>\game\localization\french"
python src/add_missing_lines.py <localisation_dir> <localisation_dir> -source_lang <source_lang> -dest_lang <dest_lang>
Example to add in French files missing lines from English files
python src/add_missing_lines.py "<...>\localisation" "<...>\localisation" -source_lang english -dest_lang french
Apply the differences between an old source version and a current source version to your current destination files.
For Imperator Rome and sooner, and new EUIV, HoI4 or Stellaris localisation format (a subdirectory for each language)
python src/apply_diff_all.py <old_localisation_dir> <current_localisation_dir>
- <old_localisation_dir> contains the localisation of the old source version
- <current_source_localisation_dir> contains the localisation of the new source version
- <current_dest_localisation_dir> contains the localisation of the old destination version
Example to apply in French files the modifications done in English
python src/apply_diff_all.py "<...>\V1\localisation\english" "<...>\V2\localisation\english" -dest_dir "<...>\V1\localisation\french"
python src/apply_diff_all.py <old_localisation_dir> <current_localisation_dir> -source_lang <source_lang> -dest_lang <dest_lang>
- <old_localisation_dir> contains the localisation of the old source version
- <current_localisation_dir> contains the localisation of both new source version and old destination version
Example to apply in French files the modifications done in English
python src/apply_diff_all.py "<...>\V1\localisation" "<...>\V2\localisation" -source_lang english -dest_lang french
The destination files are overriden so don't hesitate to have a backup before running this.
The new and edited lines contains :9 ".
If there is less than 10 modifications (according Levenshtein distance), the destination text is kept.
All the lines to translate are exported in to_translate/file_to_translate_<source_lang>.yml.
We can also add the following parameter to the command line -keys_to_ignore <path_to_file_with_a_key_a_line>, to simply copy-paste lines with these keys. It is useful when you have keys like spellcheck_ignore in the source files.
Extract existing translation from another game or mod to apply to your translation
The target is EUIV or sooner whereas the source can be CK2/Vic2 or EUIV and sooner.
python src/extract_existing_translation.py <extract_source_dir> <extract_dest_dir> <target_source_dir> <target_dest_dir> <source_lang> <dest_lang> -source_col_ck2 <source_col_ck2> -dest_col_ck2 <dest_col_ck2>
Example to add in French CK3 files some texts from CK2 files.
python src/extract_existing_translation.py "<...>\CK2\localisation" "<...>\CK2\localisation" "<...>\CK3\localization\english" "<...>\CK3\localization\french" english french -source_col_ck2 1 -dest_col_ck2 2
Example to add in French HoI IV mod files some texts from Vanilla files.
python src/extract_existing_translation.py "<...>\Steam\steamapps\common\Hearts of Iron IV\localisation" "<...>\Steam\steamapps\common\Hearts of Iron IV\localisation" "<...>\mod\localisation" "<...>\mod\localisation" english french
Extract translations from JSON files downloaded from Paratranz to apply to your translation.
This script only works for EUIV and sooner.
python src/extract_paratranz_translation.py <paratranz_dir> <localisation_dir> <language>
Example to extract french reviewed translations
python src/extract_paratranz_translation.py "<...>\paratranz" "<...>\localisation" french
By default it extracts only reviewed translation.
If you want to extract not reviewed translation, add -extract_not_review to the command.
Example to extract french translations (reviewed or not)
python src/extract_paratranz_translation.py "<...>\paratranz" "<...>\localisation" french -extract_not_review
Copy the localization of a language in other languages to allow to run your game/mod with this language with source texts instead of keys.
It works only for Imperator Rome and sooner.
The usage is explicated in this Steam guide.
python src/copy_on_other_languages.py <localization_dir> <source_lang> <dest_lang1> <dest_lang2> ...
Example to add some languages to available only in English and French (the added languages will have English text).
python src/copy_on_other_languages.py "<...>\MyMod\localisation" english korean german russian simp_chinese spanish
To compile it (after running once pip install cx_Freeze), use the following command
cxfreeze -c src/copy_on_other_languages.py
Get the list of duplicated keys in the localization to avoid localization erased by others.
The duplicated keys are searched in English localisation files only.
To get the full list of duplicated keys run the following command
python src/get_duplicates_key.py "<...>\MyMod\localisation"
To get only the list of duplicated keys which already cause a bug (the value is not the same for each duplication), add -only_different_value to the command.
python src/apply_diff.py <old_source_file> <new_source_file> <dest_file>
The destination file is override so don't hesitate to have a backup before running this.
The new and edited lines contains :9 "
Optionnal parameters :
-space_prefix <value>: Prefix (generally spaces) before key in files-keep_edited: Keep destination value in case of edition. The default behavior replace the destination value by the new source value.
Example to apply the English update from 0.11.1 to 0.11.2 to Russia file in French:
<...>\0.11.1\localisation\KR_Russia_l_english.yml <...>\0.11.2\localisation\KR_Russia_l_english.yml <...>\Translation_FR\localisation\KR_Russia_l_french.yml -space_prefix " " -keep_edited
After running this, the new and edited lines need to be fixed by hand by seeking :9 "
Go to the tests directory and run unittest
cd tests
python -m unittest discover
If some tests fails with error ModuleNotFoundError: No module named 'src', run the following command in the root directory.
On Windows:
set PYTHONPATH=%CD%
On Linux
export PYTHONPATH=${PYTHONPATH}:${PWD}
Th upload badge to GitHub action should have access to your GitHub repository. Strongly recommend store it in secrets. Create a personal access token with the repo permission. Create a secret named ACCESS_TOKEN in your repository and copy access token to the secret value.
The project has an MIT license.