From 645ccba0f25fd5e123994f8ab1b3a02d9b8074b5 Mon Sep 17 00:00:00 2001 From: Dave Whiteland Date: Tue, 24 Jun 2014 13:11:38 +0100 Subject: add i18n page (from wiki) to dev docs --- docs/developers/i18n.md | 143 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 143 insertions(+) create mode 100644 docs/developers/i18n.md (limited to 'docs') diff --git a/docs/developers/i18n.md b/docs/developers/i18n.md new file mode 100644 index 000000000..480d0d954 --- /dev/null +++ b/docs/developers/i18n.md @@ -0,0 +1,143 @@ +--- +layout: page +title: Internationalisation (for devs) +--- + +# Internationalisation in the code + +

+ This page describes some technical aspects of internationalising the + Alaveteli code. It's mostly aimed at devs who are working on the + codebase — if you just want to translate Alaveteli into your + own langauge, see this page on + Translating Alaveteli + instead. +

+ + +## Deployment notes + +Deployed translations for the project live in ``locale/``. + +Translations live in the project page at +[Transifex](https://www.transifex.net/projects/p/alaveteli/) and should +be submitted there. + +To deploy, say, English and Spanish translations at once: + + * Ensure their PO files are at ```locale/en/app.po``` and ```locale/es/app.po``` + (for example, by downloading them from Transifex) + * Set AVAILABLE_LOCALES + to en es + +The ``pot``-file at ``locale/app.pot`` acts as the template for PO files. When +new translation strings have been added to the source, this ``pot``-file can be +updated using the script at ``script/generate_pot.sh``. This looks for new +translatable strings in the source and creates entries in the ``pot``-file. + +For more details about the translations, see the page about +[translating Alaveteli]({{ site.baseurl }}customising/translation). + + +## Technical implementation details + +### Getting the current locale + +This is complicated by the fact that there are two competing ways to define a +locale+territory combination. The POSIX (and `gettext` and Transifex) way is +like `en_GB`; the Rails way is like `en-US`. Because we are using gettext and +Transifex for translations, we must deal with both. Wherever you need to know +the Rails version of the currently selected locale, use `I18n.locale`; wherever +you want to know the POSIX version of the locale, use `FastGettext.locale`. + +## I18n in templates + +Before you add i18n strings to the source, you should read +[internationalisation guidelines](http://mysociety.github.io/internationalization.html) +that apply to all our projects. + +Some hints for adding the strings into the Alaveteli code: + +* Simple strings: ```<% = _("String to translate") %>``` +* Strings that include variables: give the translator a hand by inserting + strings that can be interpolated, so the variable has meaning. For example, + ```<%= "Nothing found for '" + h(@query) + "'" %>``` might become ```<%= + _("Nothing found for '{{search_terms}}'", :search_terms => h(@query)) %>``` +* Strings containing numbers: ```<%= n_('%d request', '%d requests', @quantity) % @quantity %>``` +* We allow some inline HTML where it helps with meaningful context, for example: + +``` +_('Browse all or ask us to add it.', + :browse_url => @browse_url, :add_url => @add_url) +``` + +Similar rules can apply to strings in the python source code, as long as you +import ```_```, ```n_```, etc. + +## Programmatic access of translated PublicBodies + +Apart from the templates, the only other area of i18n currently implemented is +in the PublicBodies. + +The implementation allows for getting different locales of a PublicBody like so: + +```ruby + PublicBody.with_locale("es") do + puts PublicBody.find(230).name + end +``` + +Usually, that's all the code you need to know about. There's a method +```self.locale_from_params()``` available on all models which returns a locale +specified as ```locale=xx``` in the query string, and which falls back to the +default locale, that you can use in conjunction with the ```with_locale``` +method above. All the joining on internal translation tables should usually be +handled automagically -- but there are some exceptions, that follow below. + +### Overriding model field setters + +Internally, we use the [Globalize plugin](https://rubygems.org/gems/globalize) +to localize model fields. Where column "foo" has been marked in the model as +```:translates```, globalize overrides ```foo.baz = 12``` to actually set the +value in column ```baz``` of table ```foo_translations```. + +A side effect of the way it does this is that if you wish to override a +specific attribute setter, you will need to explicitly call the Globalize +machinery; something like: + +```ruby + def name=(name) + globalize.write(self.class.locale || I18n.locale, "name", name) + self["name"] = short_name + # your other stuff here + end +``` + +### Searching + +The ```find_first_by_``` and ```find_all_by_``` magic methods +should work. If you want to do a more programmatic search, you will need to +join on the translation table. For example: + +```ruby + query = "#{translated_attr_name(someattr) = ? AND #{translated_attr_name('locale')} IN (?)" + locales = Globalize.fallbacks(locale || I18n.locale).map(&:to_s) + find( + :first, + :joins => :translations, + :conditions => [query, value, locales], + :readonly => false + ) +``` + +You may also need to do some lower-level SQL joins or conditions. See +```PublicBodyController.list``` for an example of a query that has a condition +that is explicitly locale-aware (look for the ```locale_condition``` variable) + + +## I18n in URLs + +We have tried using the [translate_routes plugin](https://github.com/raul/translate_routes) +to localize URLs. This looks up URL segments as translation strings in a YAML +file at```config/i18n-routes.yml```. However, we no longer use it because we +found it was overly complex. -- cgit v1.2.3 From 1ec977edae73b9257f9e93fe2475f861e1023274 Mon Sep 17 00:00:00 2001 From: Dave Whiteland Date: Tue, 24 Jun 2014 13:19:04 +0100 Subject: move release manager note (needs more work) --- docs/customising/translation.md | 9 ++------- docs/developers/i18n.md | 10 ++++++++-- 2 files changed, 10 insertions(+), 9 deletions(-) (limited to 'docs') diff --git a/docs/customising/translation.md b/docs/customising/translation.md index bcf6514e5..a30782acb 100644 --- a/docs/customising/translation.md +++ b/docs/customising/translation.md @@ -110,13 +110,8 @@ translate the text that comes *after* the `|`. need to understand how to make any text you add easy for translators to work with.** -Please read our [internationalisation +See the page about [internationalising Alaveteli]({{site.baseurl}}docs/developers/i18n/). +You should also read mySociety's [internationalisation guide](http://mysociety.github.io/internationalization.html) for our advice on using strings that will need translation. This applies across all mySociety projects, not just Alaveteli. - -The release manager will enforce a translation freeze just before a new release -is cut. During such time, you must not introduce new strings to the code if -your work is due for inclusion in this release. This is necessary to allow -translators time to complete and check their translations against all the known -strings. diff --git a/docs/developers/i18n.md b/docs/developers/i18n.md index 480d0d954..34ef2a28c 100644 --- a/docs/developers/i18n.md +++ b/docs/developers/i18n.md @@ -10,11 +10,10 @@ title: Internationalisation (for devs) Alaveteli code. It's mostly aimed at devs who are working on the codebase — if you just want to translate Alaveteli into your own langauge, see this page on - Translating Alaveteli + translating Alaveteli instead.

- ## Deployment notes Deployed translations for the project live in ``locale/``. @@ -134,6 +133,13 @@ You may also need to do some lower-level SQL joins or conditions. See ```PublicBodyController.list``` for an example of a query that has a condition that is explicitly locale-aware (look for the ```locale_condition``` variable) +## Translation and releases + +The release manager will enforce a translation freeze just before a new release +is cut. During such time, you must not introduce new strings to the code if +your work is due for inclusion in this release. This is necessary to allow +translators time to complete and check their translations against all the known +strings. ## I18n in URLs -- cgit v1.2.3 From a662f2ae1a7dbfc40621abbb6b779aad2f01e142 Mon Sep 17 00:00:00 2001 From: Dave Whiteland Date: Tue, 24 Jun 2014 14:58:13 +0100 Subject: rewrite bad sentence/spelling --- docs/developers/i18n.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/developers/i18n.md b/docs/developers/i18n.md index 34ef2a28c..67e7e5be8 100644 --- a/docs/developers/i18n.md +++ b/docs/developers/i18n.md @@ -9,7 +9,7 @@ title: Internationalisation (for devs) This page describes some technical aspects of internationalising the Alaveteli code. It's mostly aimed at devs who are working on the codebase — if you just want to translate Alaveteli into your - own langauge, see this page on + own language, see translating Alaveteli instead.

-- cgit v1.2.3 From 36ccd092d91da93774979d445203c29156880079 Mon Sep 17 00:00:00 2001 From: Dave Whiteland Date: Wed, 25 Jun 2014 17:30:24 +0100 Subject: fix broken links --- docs/developers/i18n.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) (limited to 'docs') diff --git a/docs/developers/i18n.md b/docs/developers/i18n.md index 67e7e5be8..51d6cada1 100644 --- a/docs/developers/i18n.md +++ b/docs/developers/i18n.md @@ -26,7 +26,7 @@ To deploy, say, English and Spanish translations at once: * Ensure their PO files are at ```locale/en/app.po``` and ```locale/es/app.po``` (for example, by downloading them from Transifex) - * Set AVAILABLE_LOCALES + * Set AVAILABLE_LOCALES to en es The ``pot``-file at ``locale/app.pot`` acts as the template for PO files. When @@ -35,7 +35,7 @@ updated using the script at ``script/generate_pot.sh``. This looks for new translatable strings in the source and creates entries in the ``pot``-file. For more details about the translations, see the page about -[translating Alaveteli]({{ site.baseurl }}customising/translation). +[translating Alaveteli]({{ site.baseurl }}docs/customising/translation/). ## Technical implementation details @@ -95,7 +95,7 @@ handled automagically -- but there are some exceptions, that follow below. ### Overriding model field setters -Internally, we use the [Globalize plugin](https://rubygems.org/gems/globalize) +Internally, we use the [Globalize plugin](https://github.com/globalize/globalize) to localize model fields. Where column "foo" has been marked in the model as ```:translates```, globalize overrides ```foo.baz = 12``` to actually set the value in column ```baz``` of table ```foo_translations```. -- cgit v1.2.3 From 07d6c2f5667b45db22b8426ce0f4c948fb3c8cec Mon Sep 17 00:00:00 2001 From: Dave Whiteland Date: Wed, 25 Jun 2014 17:33:05 +0100 Subject: rewrites and fixes --- docs/customising/translation.md | 44 +++++++++++++++++++++++++---------------- docs/developers/i18n.md | 31 ++++++++++++++--------------- 2 files changed, 42 insertions(+), 33 deletions(-) (limited to 'docs') diff --git a/docs/customising/translation.md b/docs/customising/translation.md index a30782acb..6558be2a0 100644 --- a/docs/customising/translation.md +++ b/docs/customising/translation.md @@ -14,18 +14,23 @@ title: Translation ## Alaveteli's translations -The software translations are implemented using GNU gettext, and the resource -files are managed in Transifex. +You don't need to be a programmer to translate Alaveteli -- we use an external +website called Transifex to help manage translations. This makes it easy for +translators to get to work, but it does mean you (or your technical team) +need to do a little extra work to get those translations back into Alaveteli +when they are ready. The Transifex project is at -[https://www.transifex.net/projects/p/alaveteli](https://www.transifex.net/projects/p/alaveteli) -- you'll probably want an account there (ask on the mailing -list). It has a fairly easy-to-use interface for contributing translations. +[https://www.transifex.net/projects/p/alaveteli](https://www.transifex.net/projects/p/alaveteli) +-- you'll probably want an account there (ask on the mailing list). It has a +fairly easy-to-use interface for contributing translations. -There are three roles in the translation process, and each one is described -below: **translator**, **developer**, and **release manager**. You probably only -need to know about the one that applies to you. +Alaveteli implements translations using GNU gettext and `.pot` & `.po` files. +If you're a developer, you should read +[internationalising Alaveteli]({{ site.baseurl }}docs/developers/i18n/). -## Translation process: translator's view + +## What a translator needs to do **If you're just working on translating Alaveteli into a language you know, then this section is for you.** @@ -104,14 +109,19 @@ they do not appear on the site anywhere at the moment, and when they do, they will only be used in the admin interface. If you do translate them, only translate the text that comes *after* the `|`. -## Translation process: developers' view -**If you're writing new code for Alaveteli, then you're a developer, and you -need to understand how to make any text you add easy for translators to work -with.** +## How the translations get into Alaveteli + +In order to get the translated strings from Transifex into Alaveteli, follow +the instructions in these [deployment notes]({{ site.baseurl }}docs/developers/i18n/#deployment-notes). +This will be the job of the technical people on your team (or +even mySociety's release manager) -- if translators aren't technical, they can +use Transifex without needing to worry about this. -See the page about [internationalising Alaveteli]({{site.baseurl}}docs/developers/i18n/). -You should also read mySociety's [internationalisation -guide](http://mysociety.github.io/internationalization.html) for our advice on -using strings that will need translation. This applies across all mySociety -projects, not just Alaveteli. + +## Developers and internationalisation + +If you're writing new code for Alaveteli, then you're a developer, and you +need to understand how to make any text you add easy for translators to work +with -- see the page about +[internationalising Alaveteli]({{site.baseurl}}docs/developers/i18n/). diff --git a/docs/developers/i18n.md b/docs/developers/i18n.md index 51d6cada1..521ca5768 100644 --- a/docs/developers/i18n.md +++ b/docs/developers/i18n.md @@ -22,17 +22,23 @@ Translations live in the project page at [Transifex](https://www.transifex.net/projects/p/alaveteli/) and should be submitted there. -To deploy, say, English and Spanish translations at once: +For example, to deploy English and Spanish translations at once: * Ensure their PO files are at ```locale/en/app.po``` and ```locale/es/app.po``` (for example, by downloading them from Transifex) * Set AVAILABLE_LOCALES to en es - -The ``pot``-file at ``locale/app.pot`` acts as the template for PO files. When -new translation strings have been added to the source, this ``pot``-file can be -updated using the script at ``script/generate_pot.sh``. This looks for new -translatable strings in the source and creates entries in the ``pot``-file. + +To update the `.pot` and `.po` files for each language, run: + + bundle exec rake gettext:store_model_attributes + +followed by: + + bundle exec rake gettext:find + +If `gettext:find` only creates the file `locale/im-config.pot` then you need to +unset the `TEXTDOMAIN` environment variable and try again. For more details about the translations, see the page about [translating Alaveteli]({{ site.baseurl }}docs/customising/translation/). @@ -43,7 +49,7 @@ For more details about the translations, see the page about ### Getting the current locale This is complicated by the fact that there are two competing ways to define a -locale+territory combination. The POSIX (and `gettext` and Transifex) way is +locale+territory combination. The POSIX (and gettext and Transifex) way is like `en_GB`; the Rails way is like `en-US`. Because we are using gettext and Transifex for translations, we must deal with both. Wherever you need to know the Rails version of the currently selected locale, use `I18n.locale`; wherever @@ -70,8 +76,7 @@ _('Browse all or ask us to ad :browse_url => @browse_url, :add_url => @add_url) ``` -Similar rules can apply to strings in the python source code, as long as you -import ```_```, ```n_```, etc. +Similar rules can apply to strings in the Ruby source code. ## Programmatic access of translated PublicBodies @@ -139,11 +144,5 @@ The release manager will enforce a translation freeze just before a new release is cut. During such time, you must not introduce new strings to the code if your work is due for inclusion in this release. This is necessary to allow translators time to complete and check their translations against all the known -strings. - -## I18n in URLs +strings. See more about [translating Alaveteli]({{ site.baseurl }}docs/customising/translation/). -We have tried using the [translate_routes plugin](https://github.com/raul/translate_routes) -to localize URLs. This looks up URL segments as translation strings in a YAML -file at```config/i18n-routes.yml```. However, we no longer use it because we -found it was overly complex. -- cgit v1.2.3 From 6ca812b89cf22b12bb1cb91ba18dbcac5e038e31 Mon Sep 17 00:00:00 2001 From: Dave Whiteland Date: Thu, 3 Jul 2014 11:50:14 +0100 Subject: add .po glossary entry --- docs/glossary.md | 31 +++++++++++++++++++++++++++++++ 1 file changed, 31 insertions(+) (limited to 'docs') diff --git a/docs/glossary.md b/docs/glossary.md index 64c75c603..6e0bc8915 100644 --- a/docs/glossary.md +++ b/docs/glossary.md @@ -27,6 +27,7 @@ Definitions
  • holding pen
  • New Relic
  • MTA
    • +
  • .po files
  • production site
  • publish
  • recaptcha
    • @@ -332,6 +333,36 @@ Definitions +
    + .po file (and .pot file) +
    +
    + These are the files needed by the gettext mechanism Alaveteli uses for + localisation. A .pot file is effectively a list of all the + strings in the application that need translating. Each .po + file contains the mapping between those strings, used as keys, and their + translations for one particular language. The key is called the + msgid, and its corresponding translation is the msgstr. +
    +

    More information:

    +
      +
    • + See translating + Alaveteli for an overview from a translator's point of view. +
      • +
    • + See Internationalising + Alaveteli for more technical details. +
      • +
    • + Alaveteli is on the Transifex + website, which lets translators work on Alaveteli in a browser, without needing + to worry about this underlying structure. +
      • +
    +
    +
    +
    production site (also: live, production server)
    -- cgit v1.2.3 From 1baf9bda6b22ab6bbe8ae2d1b69f127b79273b40 Mon Sep 17 00:00:00 2001 From: Dave Whiteland Date: Thu, 3 Jul 2014 12:35:59 +0100 Subject: add release/release manager to glossary --- docs/glossary.md | 36 ++++++++++++++++++++++++++++++++++++ 1 file changed, 36 insertions(+) (limited to 'docs') diff --git a/docs/glossary.md b/docs/glossary.md index 6e0bc8915..5eb45943b 100644 --- a/docs/glossary.md +++ b/docs/glossary.md @@ -34,6 +34,7 @@ Definitions
  • redacting
  • regular expression
  • request
    • +
  • release
  • response
  • Ruby on Rails
  • Sass
    • @@ -512,6 +513,41 @@ Definitions +
    + release (also: release manager) +
    +
    + We issue new releases of the Alaveteli code whenever key + work (new features, improvements, bugfixes, and so on) have been added to + the core code. Releases are identified by three numbers: major, minor, and + — if necessary — a patch number. We recommend you always use + the latest version. The process is handled by the Alaveteli release + manager, who decides what changes are to be included in the + current release, and the cut-off date for the work. Currently this is + Alaveteli's lead developer at mySociety. +
    +

    More information:

    + +
    +
    +
    request
    -- cgit v1.2.3 From 4730bdea85bf7e294885d89e9ebcc9a1151e73ac Mon Sep 17 00:00:00 2001 From: Dave Whiteland Date: Thu, 3 Jul 2014 12:38:56 +0100 Subject: fix quirky alternative alphabetic order in glossary --- docs/glossary.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) (limited to 'docs') diff --git a/docs/glossary.md b/docs/glossary.md index 5eb45943b..7a7c5d003 100644 --- a/docs/glossary.md +++ b/docs/glossary.md @@ -409,15 +409,6 @@ Definitions information provided in response. -
    - response -
    -
    - A response is the email sent by an - authority in reply to - a user's requests. -
    -
    recaptcha
    @@ -561,6 +552,15 @@ Definitions to all the requests it sends. +
    + response +
    +
    + A response is the email sent by an + authority in reply to + a user's requests. +
    +
    Ruby on Rails (also Rails)
    -- cgit v1.2.3 From 230b2fee5ddf656344bfac53dea7f2a10c6c0a4b Mon Sep 17 00:00:00 2001 From: Dave Whiteland Date: Thu, 3 Jul 2014 12:54:24 +0100 Subject: rewritten i18n/translation pages with @crowbot's comments in mind --- docs/customising/translation.md | 62 ++++++++++++++++++++++++++++++++++++----- docs/developers/i18n.md | 29 +++++++++++++------ 2 files changed, 76 insertions(+), 15 deletions(-) (limited to 'docs') diff --git a/docs/customising/translation.md b/docs/customising/translation.md index 6558be2a0..d4ccedfa7 100644 --- a/docs/customising/translation.md +++ b/docs/customising/translation.md @@ -12,6 +12,39 @@ title: Translation it. This page explains how.

    +## Alaveteli already contains translations! + +Alaveteli ships ready to run in a number of different languages. +If Alaveteli has already been translated into the language (or languages) you +need, you just need to configure it -- see +[`AVAILABLE_LOCALES`]({{ site.baseurl }}docs/customising/config/#available_locales). + +[Look in the `locale/` directory](https://github.com/mysociety/alaveteli/tree/master/locale) +to see what translations are already available. Some are complete +translations of the site. Others are only partial -- either because the translations +have not been finished yet, or else because the translators have not updated the +texts since developers changed or added text on the site. + +There are two reasons the translations may need more work before you can use them: + +* **the language you want is not one of those we already have**
    In this + case, there will be no entry in ``locale/`` for it, because nobody has yet + translated Alaveteli into your language. See the rest of this page to learn + how to add a new translation. + +* **the translation for your language is incomplete, or lagging behind**
    + This might simply be because it is a work in progress. Furthermore, sometimes + an incomplete translation already covers all the areas of the site you need + anyway. Of course, you can add to a partial translation, but it's a good idea + to check with us first, since we'll probably know who is working on the + current translation and what state it's in. + +Translators are members of the Alaveteli +[community]({{site.baseurl}}community/), and often work separately from the +developers. This means translations can lag a little behind the code. However, +our release process includes a "translation freeze", which gives the +translators a chance to catch up -- read the rest of this page for details. + ## Alaveteli's translations You don't need to be a programmer to translate Alaveteli -- we use an external @@ -25,7 +58,8 @@ The Transifex project is at -- you'll probably want an account there (ask on the mailing list). It has a fairly easy-to-use interface for contributing translations. -Alaveteli implements translations using GNU gettext and `.pot` & `.po` files. +Alaveteli localises strings using GNU gettext and +.pot & .po files. If you're a developer, you should read [internationalising Alaveteli]({{ site.baseurl }}docs/developers/i18n/). @@ -35,20 +69,28 @@ If you're a developer, you should read **If you're just working on translating Alaveteli into a language you know, then this section is for you.** +> Remember that Alaveteli +> [already comes with some translations](#alaveteli-already-contains-translations), +> so check first that you really need to do this. Maybe someone has already +> translated Alaveteli into the language you need! + When a developer adds a new feature to the user interface in Alaveteli, they use some code to mark sentences or words ("strings") that they think will need to be translated. -When the Alaveteli release manager is planning a release, they will upload a -template containing all the strings to be translated (called a POT) to -Transifex. This causes your own translations in Transifex to be updated with +When the Alaveteli +release manager +is planning a release, they will upload a +template containing all the strings to be translated (called a +.pot file) +to Transifex. This causes your own translations in Transifex to be updated with the latest strings. When you visit Transifex, it will prompt you to fill out values for all new strings, and all strings that have been modified. In the case where a string has only been slightly modified, such as with punctuation ("Hello" has become "Hello!"), Transifex will suggest a suitable translation for you (look for the -"suggestions" tab under the source string). +*Suggestions* tab under the source string). In order for this feature to work properly, the release manager has to download your translations, run a program that inserts the suggestions, and then upload @@ -64,11 +106,12 @@ The release manager will also give you a **translation deadline**. After this date, you can continue to contribute new translations, but they won't make it into the release. + ### General notes on translation in Transifex Some strings will have comments attached to them from the Alaveteli application developers about the context in which the text appears in the -application — these comments will appear under the 'Details' tab for the text +application — these comments will appear under the *Details* tab for the text in Transifex. Some strings will have **placeholders** in them to indicate that Alaveteli @@ -115,7 +158,7 @@ translate the text that comes *after* the `|`. In order to get the translated strings from Transifex into Alaveteli, follow the instructions in these [deployment notes]({{ site.baseurl }}docs/developers/i18n/#deployment-notes). This will be the job of the technical people on your team (or -even mySociety's release manager) -- if translators aren't technical, they can +even mySociety's release manager). If translators aren't technical, they can use Transifex without needing to worry about this. @@ -125,3 +168,8 @@ If you're writing new code for Alaveteli, then you're a developer, and you need to understand how to make any text you add easy for translators to work with -- see the page about [internationalising Alaveteli]({{site.baseurl}}docs/developers/i18n/). + +If you are a developer or translator actively working on internationalising +Alaveteli code, you should talk to us to find out when the next release is due, +so your translations can be prepared in time to be included in it. + diff --git a/docs/developers/i18n.md b/docs/developers/i18n.md index 521ca5768..deabc99a1 100644 --- a/docs/developers/i18n.md +++ b/docs/developers/i18n.md @@ -18,18 +18,30 @@ title: Internationalisation (for devs) Deployed translations for the project live in ``locale/``. -Translations live in the project page at -[Transifex](https://www.transifex.net/projects/p/alaveteli/) and should -be submitted there. +We encourage translations to be done on +[Transifex](https://www.transifex.net/projects/p/alaveteli/) +because translators can work through its web interface rather than needing to edit the +`.po` and `.pot` files +directly. Ultimately, Transifex just captures translators' +work and turns it into the files that Alaveteli needs (using gettext). + +### How to get the latest translations onto your site For example, to deploy English and Spanish translations at once: - * Ensure their PO files are at ```locale/en/app.po``` and ```locale/es/app.po``` + * Ensure their `.po` files are at ```locale/en/app.po``` and ```locale/es/app.po``` (for example, by downloading them from Transifex) * Set AVAILABLE_LOCALES to en es -To update the `.pot` and `.po` files for each language, run: +### How to add new strings to the translations + +You need to do this if you've added any new strings to the code that need +translations (or if you change an existing one). + +To update the +`.po` or `.pot` files +for each language, run: bundle exec rake gettext:store_model_attributes @@ -51,9 +63,10 @@ For more details about the translations, see the page about This is complicated by the fact that there are two competing ways to define a locale+territory combination. The POSIX (and gettext and Transifex) way is like `en_GB`; the Rails way is like `en-US`. Because we are using gettext and -Transifex for translations, we must deal with both. Wherever you need to know -the Rails version of the currently selected locale, use `I18n.locale`; wherever -you want to know the POSIX version of the locale, use `FastGettext.locale`. +Transifex for translations, we must deal with both. + + * for the Rails version of the currently selected locale, use `I18n.locale` + * for the POSIX version of the locale, use `FastGettext.locale` ## I18n in templates -- cgit v1.2.3