Feather Wiki

A tiny tool for simple, self-contained wikis!

Learn /

Translation

Created:

Feather Wiki makes it painless to contribute a translation into a different language. All it takes is replacing the English text in a translation file with the translated text in your own language.

There are 2 ways to go about contributing a Feather Wiki translation: 1) the easy way or 2) the coder way. The "coder way" allows it to be added to the project more easily, but the "easy way" provides a way with fewer steps at the cost of taking longer to add to the project. No matter which path you take, the new translations will still need to be built and uploaded before they will be widely available.

1. The Easy Way #

To create a new translation, create a new Translation Issue with the name "Translation to [language]" where [language] is the name of the language you are translating to. If you are translating for a particular region, for example Spain Spanish versus Central American Spanish, please also note that in the title. The translation template includes the contents of the base en-US.json file, which contains all of the required translation strings, so please use it to begin your translation.

Using the JSON as a base to ensure you have all of the required translation keys, replace the English text inside the quotation marks after each colon (:) with the correct translation for your target language. You can search the project files for the translate keys from the JSON if the context for each word or phrase is not clear enough from the key alone. If any translation strings are missing from the list when you are finished, the US English string will be used in its place.

Please note that this method will take longer to add into the project than the method for coders below. If you can make sure the resulting JSON is valid according to the instructions above and include the language tag as specified below, that will make the process much faster!

If any new translation strings are added to the project in the future, I may reach out to you to add the translation to the file so it can remain complete. If you are able to help, it would be very appreciated!

2. The Coder Way #

Feather Wiki uses JSON files in the locales folder to generate builds in languages other than US English (the default language because it's the only language I know).

To create a new translation, fork the repository and copy the en-US.json file with the name of the correct locale code you would like to translate to. The en-US.json file will always contain all of the required translation strings, so you should make sure your translation includes all of the keys present there. If any translation strings are missing from the file, the US English string will be used in its place.

Naming the Locale File #

The name of the file is used as is inside the resulting HTML file's lang attribute, so it must be valid.

You can find the official ISO 639 list of locale codes here: https://www.loc.gov/standards/iso639-2/php/code_list.php. Please use the 2-character ISO 639-1 (set 1) language code whenever possible and only use the 3-character 639-2 (set 2) code if a code from set 1 does not exist. This locale code must be lowercase in the file name, and it must be included in the code list.

Regions #

If you are translating to a regional dialect of a language, for example Spanish in Spain versus Central America, you may specify that in the name of the file, i.e. es-ES.json for Spain and es-013.json for Central America. You can find all the possible region subtags most conveniently in this JavaScript file from the official r12a language subtag lookup tool: https://github.com/r12a/r12a.github.io/blob/master/apps/subtags/regions.js. There are other ways to create valid language tags, but most of the time, it is unnecessarily complicated to go beyond locale and region codes. If you want to learn more about creating valid language tags, the W3C has a comprehensive guide for coming up with the exact language tag you are looking for, but it's a bit much for this project.

Translating #

Using the en-US.json file as a base to ensure you have all of the required translation keys, replace the English text with the correct translation for your target language. You can search the project files for the translate keys in the JSON file if the context is not clear enough from the key alone.

Please ensure that your final JSON is valid; for example, if using quotation marks " in a translation string, ensure that they are correctly escaped with backslashes: \\". Likewise, when you encounter variables within the original string, please keep the variable as it appears in the original US English locale file. For example, imageUsedIn includes ${i.pgs.length} in the string for the app to denote the number of pages an image is used in, so it should be used as is in the correct location of the translated sentence.

Pull Request #

Once you've finished your valid JSON translation file, push it to your fork and create a pull request with the name "Translation to [language]" where [language] is the name of the language you are translating to. The translation file will be reviewed to make sure everything looks valid, and if everything checks out, your translation will be used to create a new Feather Wiki translation! New translations will be linked to from the Downloads page of the Feather Wiki website and included in the Releases list.

Future Changes #

If any new translation strings are added to the project in the future, I may reach out to you to add the translation file so it can remain complete. If you are able to help, it would be very appreciated!

Extension Translations #

If you are interested in translating any extensions that are more word-heavy (like the Import/Export extension, you can follow the same process as above, but instead of putting the file in the locales folder, simply duplicate the extension file within the extensions folder and include the language tag after an underscore in the file name, for example data-import-export_es-ES.js for Spain Spanish or full-search_jp.js for Japanese.

Once the files have been checked in the pull request, they will be linked to from the extension page on the website.