This repository encompasses work to create a Stellaris namelist mod generator tool to facilitate the creation of Stellaris namelists.
For an example of a namelist mod created with this tool see the following links:
Osiris's Namelists for Stellaris @ GitHub
Osiris's Namelists for Stellaris @ Steam
Osiris's Namelists for Stellaris @ Paradox Plaza
For information on the generator tool that made this mod, keep reading.
The generator is a Python-based command line tool. It requires a csv file of names which it converts into the txt and yml files in the proper directory structure. It doesn't completely generate the mod for you, but does the heavy lifting. See the Issues and Limitations section below for what it can't do for you.
- Creates namelists from one or more CSV files and produces a single mod for all the namelists.
- Has resolved the %SEQ% issue introduced with Stellaris 3.6.0
- Write a blank csv template to fill out.
- Basic localization.
- Optional translation of localization.
Follow the steps below to create your own namelist mod.
The tool is written in Python and therefore requires Python on your computer. See the Python Getting Started Page.
This tool uses Poetry for dependency management and packaging. See these installation instructions.
Once Poetry is installed, namelist-mod-gen(NMG) can bet setup with the following command:
poetry install
This will install any dependencies and setup a virtual environment to run the tool.
To print the basic usage, execute the following:
./namelist_mod_gen.py --help
or
poetry run python src/namelist_mod_gen/namelist_mod_gen.py --help
The tool will generate a new CSV template that can be loaded into Google Sheets or Excel to populate a namelist with the following command:
<root_directory>/namelist_mod_gen/namelist_mod_gen.py csv -d <desired_template_name.csv>
or
poetry run python namelist_mod_gen/namelist_mod_gen.py csv -d <desired_template_name.csv>
The fastest and most basic usage of NMG is to generate a mod from a directory of CSV files without translation. This can be done with the following command:
<root_directory>/namelist_mod_gen/namelist_mod_gen.py mod -n </path/to/namelist/csv/dir/> -a <author_name> -m <mod_name>
or
poetry run python namelist_mod_gen/namelist_mod_gen.py mod -n </path/to/namelist/csv/dir/> -a <author_name> -m <mod_name>
This will build the mod directory structure, convert the CSV file into namelist files for each localisation, creating all files in the original english language for all language directories. This is the basic requirement for namelists to appear for users of the mod from non-English locales.
In order to translate namelists at no cost, NMG uses a multi-tiered cascading strategy with steps that execute in order as follows:
- First, it checks a database for previously translated names to use for a given namelist.
- Any remaining untranslated names for a particular namelist are then translated using Google's API. Most often this is enough to translate an entire namelist.
- Should there be any more untranslated names, it then uses MyMemory's API. This service's free tier is capped at 5000 characters per day.
- If any names still remain, the Deepl Translation API is used. This service is capped at 500,000 characters per month and requires registration. Note you DO NOT have to use this. If the API key isn't present in the environment, this mode of translation will be skipped.
- Any remaining untranslated texts are translated using EasyNMT, a machine-learning based translation tool.
There are future plans to allow the order of these translations to be fully customizable as well as allow custom translators to be used. This work is already in the design stage and will be created as a separate module from NMG that it will import.
NMG stores translated names in a postgres database in order to cache them for future use. If you do not have postgres installed, see the following links for help:
MacOS Homebrew Postgres Install Tutorial - Recommended method. MacOS Install Tutorial Windows Install Tutorial
Once postgres is installed, we need to create a user and initialize a database. Run the following commands:
>createuser nmg
>createdb translations -O nmg
This will create the user NMG uses as well as the database to store translations.
In order for the tool to perform translations using DeepL, you will have to get an authentication key from their website. A free option is available that allows 500,000 characters per month to be translated.
Visit this link to sign up for an account: Deepl Website
Once you have an account you can find the authentication key at the bottom of the account summary page: Account Summary Page
The mod-gen tool expects to find this as an environment variable named DEEPL_AUTH_KEY. To set the environment variable, follow the links
below for your operating system:
MacOS/Linux Environment Variable Instructions Windows Environment Variable Instructions
If this variable is not set, translation will still work, but it won't use DeepL as one of the sources for translation.
To generate translated namelists, run NMG as follows, adding -t or --translate to the earlier command:
<root_directory>/namelist_mod_gen/namelist_mod_gen.py mod -n </path/to/namelist/csv/dir/> -a <author_name> -m <mod_name> -t
or
poetry run python namelist_mod_gen/namelist_mod_gen.py mod -n </path/to/namelist/csv/dir/> -a <author_name> -m <mod_name> -t
For an example of output generated by NMG using translation, visit the Github repo for Osiris's Namelists for Stellaris.
There are a number of other command line options not explicitly introduced so far in this README. The full list of options can be seen with the following command:
<root_directory>/namelist_mod_gen/namelist_mod_gen.py --help
or
poetry run python namelist_mod_gen/namelist_mod_gen.py --help
This will list the modes that NMG can run in. To get options for each mode, invoke the mode with a --help command, for example:
<root_directory>/namelist_mod_gen/namelist_mod_gen.py mod --help
Details regarding the usage of each option will be printed.
These are the known limitations and issues. Some may be addressed in the future.
- Does not currently create mod descriptor files.
- Translation is still developmental.
- Sometimes translators, especially machine learning ones, return nonsensical translations.
For issues, visit the issues page in this repository.
The easiest way to contribute a namelist to the mod is to fill out the github issue for submitting namelists here:
Osiris's Namelist Mod Contribution
The best way is to create an issue. You can also reach out to Osiris on Steam.
Q: %SEQ Is showing up in my fleet and/or army names when I provide sequential names.
A: Stellaris now expects namelists to use key value pairs that connect tne namelist in the common directory with
the associated yml file in the localization directory. If it fails to find the value associated with the key, it will display %SEQ%. This can happen for multiple reasons:
- The localization file with the key value pairs doesn't exist.
- The localization file is not in the correct directory (
<mod_root>/localisation/english/name_lists). - The keys in the namelist txt file don't match the keys in the localization file.
- The values in the localization file don't use supported sequence keys.
- The namelist and namelist localization file were NOT saved as UTF with BOM-8 encoding (Osiris's Namelist Mod Generator does this for you, but it can be done with Notepad++ as well from the encoding menu)
For a working example see the Osiris's namelist mod files.
Q: My namelist title doesn't show up in the namelist picker when creating my empire, but instead shows up as namelist_XXXX
A: This can also happen for multiple reasons related to Stellaris not finding or processing the file:
- The localization file isn't in the correct directory.
- You HAVE saved the file as UTF with BOM-8 encoding. Apparently the namelist picker in Stellaris does not like BOM-8.