Merge pull request #82 from mweimerskirch/contributing-translations

Detailed description on how to add new languages

CONTRIBUTING.md

@@ -55,3 +55,29 @@ Our community review process for `non-trivial` PRs is the following:
 4. **At least two** members of the team will approve and finally merge the request into `dev` 🎉.
 
 This process might be slow as community members have different schedules and time to dedicate to the Paperless project. However it ensures community code reviews are as brilliantly thorough as they once were with @jonaswinkler.
+
+# Adding a new language
+
+This section describes how new languages can be added to the code.
+If a language has already been added, and you would like to contribute new translations or change existing translations, please read the "Translation" section in the README.md file for further details on that.
+
+If you would like the project to be translated to another language, first head over to https://crwd.in/paperless-ngx to check if that language has already been enabled for translation.
+If not, please request the language to be added by creating an issue on GitHub. The issue should contain:
+
+* English name of the language (the localized name can be added on Crowdin).
+* ISO language code. A list of those can be found here: https://support.crowdin.com/enterprise/language-codes/
+* Date format commonly used for the language, e.g. dd/mm/yyyy, mm/dd/yyyy, etc.
+
+After the language has been added and some translations have been made on Crowdin, the language needs to be enabled in the code.
+Note that there is no need to manually add a .po of .xlf file as those will be automatically generated and imported from Crowdin.
+The following files need to be changed:
+
+* src-ui/angular.json (under the _projects/paperless-ui/i18n/locales_ JSON key)
+* src/paperless/settings.py (in the _LANGUAGES_ array)
+* src-ui/src/app/services/settings.service.ts (inside the _getLanguageOptions_ method)
+
+Please add the language in the correct order, alphabetically by locale.
+Note that _en-us_ needs to stay on top of the list, as it is the default project language
+
+If you are familiar with Git, feel free to send a Pull Request with those changes.
+If not, let us know in the issue you created for the language, so that another developer can make these changes.

README.md

@@ -88,13 +88,15 @@ The documentation for Paperless-ng is available on [ReadTheDocs](https://paperle
 
 # Translation
 
-Paperless is available in many different languages and coordinated at Crowdin. If you want to help out by translating paperless into your language, please head over to https://crwd.in/paperless-ngx, and thank you! Some notes about translation:
+Paperless-ngx is available in many languages that are coordinated on Crowdin. If you want to help out by translating paperless-ngx into your language, please head over to https://crwd.in/paperless-ngx, and thank you! More details about adding new languages to the code can be found in [CONTRIBUTING.md](https://github.com/paperless-ngx/paperless-ngx/blob/master/CONTRIBUTING.md#adding-a-new-language). Some notes about translation:
 
-- There are two resources. "src-ui/messages.xlf" is what contains the translation strings for the front end. This is important. "django.po" contains strings for the administration section of paperless, which is nice to have translated.
-- Most of the front-end strings are used on buttons, menu items, etc. so ideally the translated string should not be much longer than the English original.
+- There are two resources:
+  - "src-ui/messages.xlf" contains the translation strings for the front end. This is the most important.
+  - "django.po" contains strings for the administration section of paperless, which is nice to have translated.
+- Most of the front-end strings are used on buttons, menu items, etc., so ideally the translated string should not be much longer than the English original.
 - Translation units may contain placeholders. These usually mean that there's a name of a tag or document or something in the string. You can click on the placeholders to copy them.
 - Translation units may contain plural expressions such as `{PLURAL_VAR, plural, =1 {one result} =0 {no results} other {<placeholder> results}}`. Copy these verbatim and translate only the content in the inner `{}` brackets. Example: `{PLURAL_VAR, plural, =1 {Ein Ergebnis} =0 {Keine Ergebnisse} other {<placeholder> Ergebnisse}}`
-- Changes to translations in crowdin will get pushed into the repository automatically.
+- Changes to translations on Crowdin will get pushed into the repository automatically.
 
 # Feature Requests