Contribute translations
The first step is to do some translating in our Crowdin workspace. Create an account and start translating in one or more languages. See Contribute a translation to Discourse for more information about that.
Add language to Discourse
These instructions are currently out of date!
You have two options when you think that the translation is ready to be included in Discourse:
-
Post in this topic and ask for your language to be included in Discourse. There might be a helpful community member who will add it for you.
-
You add it yourself.
If you do, please read on…
Requirements
You will need a development environment (Linux, macOS or Windows) and a working Transifex client. Moreover, you need to fork and clone the discourse and translations-manager git repositories.
Find the language codes
I’ll use Welsh (cy_GB) as an example to show you the next steps. First, take not of the language code used by Transifex. It will look like this:
In some cases, Transifex will use a language code that isn’t supported in Rails.
In order to find out, take a look at config/locales/plurals.rb
in the discourse
repository. For Welsh you will find a line like this:
cy: { i18n: { plural: { keys: [:one, :two, :many, :other], rule: lambda { |n| n == 1 ? :one : n == 2 ? :two : n == 8 || n == 11 ? :many : :other } } } },
So, the language code in Transifex is cy_GB
and cy
in Discourse.
Add language to translations-manager
Edit lib/translations_manager/locales.rb
in the translations-manager
repository and add the language code used by Discourse to the SUPPORTED_LOCALES
array.
Add an entry to the LANGUAGE_MAP
hash if the language code in Transifex differs from the one used by Discourse.
The diff for Welsh would look like this:
@@ -5,6 +5,7 @@ module TranslationsManager
'bs_BA',
'ca',
'cs',
+ 'cy',
'da',
'de',
'el',
@@ -44,6 +45,7 @@ module TranslationsManager
# 'language code in transifex' => 'language code in Discourse'
LANGUAGE_MAP = {
+ 'cy_GB' => 'cy',
'el_GR' => 'el',
'es_ES' => 'es',
'fr_FR' => 'fr',
Next, commit your changes and create a pull request.
Add language to Discourse
You need to wait for your pull request to be merged if you added an entry to
LANGUAGE_MAP
. If you didn’t, you can continue right away.
Run script/pull_translations.rb <language_code>
in your discourse
directory – <language_code>
is the code used by Discourse. It will download all translations from Transifex and do some post-processing afterwards.
Transliteration (optional)
Discourse generates slugs from topic titles. Those are the nice looking topic titles in URLs. For example, this topic’s URL contains: /t/how-to-add-a-new-language/14970
But that only works for ASCII characters. You can add transliteration rules for your character set by creating the following file: /config/locales/transliterate.<language_code>.yml
You can take a look at the various existing files (e.g. transliterate.ru.yml
) if you need some inspiration.
The slug generation method can be configured in the site settings. You don’t need to create transliteration rules if the users in your country are accustomed to encoded slugs or prefer to have no slugs.
You can also change the default slug generation method for your language in
site_settings.yml
.
Right-to-left (optional)
If the new language is a right-to-left script then you also need to add the <language_code>
to the rtl?
method in app/helpers/application_helper.rb
.
Final checks
Now it’s time to make sure that everything is configured correctly.
Plural rules
Discourse has two files with plural rules – for Ruby and JavaScript. Please verify that the rules match the ones defined in the The Unicode Consortium’s Plural Rules.
config/locales/plurals.rb
lib/javascripts/locale/<language_code>.js
Language name
The file config/locales/names.yml
should contain an entry for your language. Please make sure that the language code exists and that the nativeName
is correct. For Welsh it looks like this:
cy:
name: Welsh
nativeName: Cymraeg
Other files
The following files also need to exist:
vendor/assets/javascripts/moment-locale/<language_code>.js
The language code doesn’t have to match exactly. Only the part before the hyphen must match. So, for Welsh it doesn’t make any difference if the file is named
cy-gb.js
orcy.js
– they are considered the same.
Integration tests
Run the following tests suite to check for known integrity issues:
bundle exec rspec spec/integrity/i18n_spec.rb
bundle exec rspec spec/components/js_locale_helper_spec.rb
It’s also a good idea to check for obvious errors in the translation files as described in How to check locale files for errors.
Live test
Start your Rails server and test that you can change to the new language using the default locale
site setting.
Submit your Pull Request
If everything works, commit the files and send us a pull request.