mirror of
https://github.com/loot/libloot.git
synced 2026-07-27 14:16:01 -07:00
Oliver Hamlet
d9dd2f2357
For #467. Korean and Simplified Chinese expect the unofficial translation files to be dropped into the folder that holds the rest of the translation files. If the files are missing, their translations will not be included when the installer is built. The translated strings were done in Google Translate and checked in Bing Translate. They should at least be legible, if not great quality. The README now refers to Inno Setup, and the CONTRIBUTING file has been generally updated both for the switch to Inno and the recent code refactoring.
69 lines
7.2 KiB
Markdown
69 lines
7.2 KiB
Markdown
Contributing To LOOT
|
|
====================
|
|
|
|
A general guide to contributing to LOOT, may be found on [LOOT's wiki](https://github.com/loot/loot.github.io/wiki/How-To-Contribute). Information more specific to this repository is found here.
|
|
|
|
## Repository Branching Structure
|
|
|
|
The repository branching structure is pretty simple:
|
|
|
|
* The `master` branch is a ready-to-release branch. It will generally hold code newer than the latest release, but which could be prepared (ie. update version number, changelog) and packaged for release fairly quickly and easily. Code on this branch *should* be reasonably bug free and features will be complete.
|
|
* The `dev` branch is a next-release branch. It holds code that's working towards the next big release but which isn't there yet. Code is generally buggy and features incomplete (though this will vary considerably through the development cycle).
|
|
* Other branches are generally themed on specific features or groups of changes, and come and go as they are merged into one of the two above, or discarded.
|
|
|
|
## Getting Involved
|
|
|
|
The best way to get started is to comment on something in GitHub's commit log or on the [issue tracker](https://github.com/loot/loot/issues) (new tracker entries are always welcome).
|
|
|
|
Surprise pull requests aren't recommended because everything you touched may have been rewritten, making your changes a pain to integrate, or obsolete. There are only generally a few contributors at any one time though, so there's not much chance of painful conflicts requiring resolution, provided you're working off the correct branch.
|
|
|
|
When you do make a pull request, please do so from a branch which doesn't have the same name as they branch you're requesting your changes to be merged into. It's a lot easier to keep track of what pull request branches do when they're named something like `you:specific-cool-feature` rather than `you:master`.
|
|
|
|
## Translating LOOT
|
|
|
|
### General Information
|
|
|
|
LOOT supports translation into other languages, with the following limitations:
|
|
|
|
* Debug log messages and error messages generated by the libraries LOOT uses cannot be translated.
|
|
* Masterlist messages can be translated, but translations must be submitted to the masterlist maintainers for addition. Translating masterlist messages won't be covered here.
|
|
* The languages LOOT supports is hardcoded, so LOOT must be updated to include new translations.
|
|
|
|
To translate everything but masterlist messages, first fork this repository. All file paths given below are relative to its base folder.
|
|
|
|
### Translating the Installer
|
|
|
|
First check that an [Inno Setup translation](http://www.jrsoftware.org/files/istrans/) exists for your language. Unofficial translations are acceptable, but require a bit of extra handling. If there isn't an official or unofficial translation for Inno Setup, you're better off making a translation and getting it listed on the linked page before continuing.
|
|
|
|
1. Open the installer script at `src/installer.iss` in a text editor of your choice.
|
|
2. If your language only has an unofficial translation, add a `#define <Language>Exists` block for it near the top of the script, like it has been done for Korean and Simplified Chinese.
|
|
3. Add your language to the `[Languages]` section. The `Name` must be the POSIX locale code for your language. The `MessagesFile` filename is the filename of the Inno Setup translation that you checked exists. If your language only has an unofficial translation, wrap its line in `#ifdef` and `#endif` lines, again like it has been done for Korean and Simplified Chinese.
|
|
4. Translate the string(s) in the `[CustomMessages]` into your language, following the example of the existing translations. Again, if your language only has an unofficial translation, wrap its line(s) in `#ifdef` and `#endif` lines.
|
|
5. Save your changes.
|
|
|
|
### Translating the LOOT application
|
|
|
|
1. Download and install the latest version of [Poedit](http://www.poedit.net/).
|
|
2. If you are starting a new translation, select `File->New catalogue from POT file...` and choose the template file at `resources/l10n/template.pot`. In the `Catalog properties` dialog, just click `OK` without changing anything.
|
|
3. If you are updating a previous translation, open in Poedit the `loot.po` translation file in the relevant subdirectory of `resources/l10n`, then select `Catalogue->Update from POT file...` and choose the template file you downloaded. Click `OK` in the `Update summary` dialog.
|
|
4. Edit the translation file to add or update translations of the programs' text. Strings that were added since the last translation are displayed in bold and dark blue, and strings you have edited the translations of are marked with a star to the left of their source text in the main list.
|
|
5. Save the translation file with the filename `loot.po` in `resources/l10n/<locale>/LC_MESSAGES/`, where `<locale>` is your language's POSIX locale code.
|
|
|
|
Some languages may use different words or phrases for different contexts where only one word or phrase may be used for all contexts in English. While no contextual information is supplied to translators by default, it can be added on request. To request the addition of contextual information to a text string, create an issue for your request in LOOT's [source code issue tracker](https://github.com/loot/loot/issues), quoting the string for which you are requesting contextual information.
|
|
|
|
Some strings to be translated may contain special characters. Different types of special character that may be encountered are:
|
|
|
|
* Backslashes (`\`). These are used to escape backslashes and double-quotation marks (`"`) in the C++ translation strings. Don't add new backslashes into translations, and make sure all backslashes in the original string are retained in the translation.
|
|
* Formatting placeholders are used so that LOOT can substitute text or numbers that are generated at runtime into pre-made strings. They appear as a number surrounded by percentage signs, eg. `%1%`, or as `%s`. If formatting placeholders are used in the untranslated string, they **must all** be present in the translated string, or LOOT will crash when it tries to display the translated string. Placeholders can be moved around so that the sentence makes grammatical sense in the target language.
|
|
|
|
### Adding A New Translation
|
|
|
|
If you're adding a new translation, LOOT's source code must be updated to recognise it. You can do this yourself and include the changes in your translation's pull request if you wish. The files and functions which must be updated are given below.
|
|
|
|
* In [language.h](src/backend/helpers/language.h), add a static constant for the language to the `Language` class.
|
|
* In [language.cpp](src/backend/helpers/language.cpp), define the value for the constant you added, and update `Language::Language(const std::string& locale)`, `Language::Construct(const unsigned int code)` and `Language::Codes({...})` to include lines for your language.
|
|
* Add constants for the language in [api.h](src/api/api.h) and [api.cpp](src/api/api.cpp).
|
|
* In [archive.py](src/archive.py), add the language folder to the inline list on line 68.
|
|
* In [installer.iss](src/installer.iss), add an entry for your language's translation file to the `[Files]` section.
|
|
* In [LOOT Metadata Syntax.html](docs/LOOT%20Metadata%20Syntax.html), add a row for your language to the Language Codes table.
|