[FOLIO-1478] What to do about `en.json` translations Created: 10/Sep/18  Updated: 28/Feb/19  Resolved: 09/Jan/19

Status: Closed
Project: FOLIO
Components: None
Affects versions: None
Fix versions: None

Type: Task Priority: P3
Reporter: Peter Murray Assignee: Peter Murray
Resolution: Done Votes: 0
Labels: i18n, sprint54
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original estimate: Not Specified

Issue links:
Blocks
is blocked by FOLIO-1641 Create en-US and en-GB locale files Closed
is blocked by FOLIO-1642 Update localization documentation to ... Closed
is blocked by FOLIO-1643 Suppress display of `en` as a languag... Closed
Relates
relates to STCOR-261 Translations fail to load for some lo... Closed
relates to FOLIO-1296 Set up push of translated strings int... Closed
Sprint:

 Description   

Zak pointed out to Peter on Slack that there have been tickets to developers to use "Headline Capitalization" rather than "Sentence capitalization" for strings in the UI, and he wondered if this is a task we could put on translators rather than developers.

So the way the GitHub-Lokalise-GitHub round trip works right now is that the `en.json` files are explicitly excluded from being replaced in the Lokalise-to-GitHub part of the trip. This started as a safety factor for the process in case the modified `en.json` file got messed up along the way. (While sorting through how we could make Lokalise's API work for our particular needs, it was possible for one modules' `en.json` file to be overwritten by another's.) Peter kept that explicit exclusion in place, though, because using the `en.json` file from Lokalise will result in a file sorted by the translation key and with all clarifying newlines removed. It seems like module developers have their own way of arranging the keys in the translation file. This means, though, that the capitalization for `en` localization would need to remain with the developers.

One way to fix this is to create an `en_US.json` localization that puts the burden of correct capitalization on the translators. We might have to cross this bridge anyway because their will likely need to be an `en_GB.json` localization (or 'localisation' we might say?). Dealing with the capitalization would just push that to the forefront.

Proposal

  1. `en.json` is the definitive source of translation keys. A new key added by a developer in this file is imported into Lokalise. (This is the case now for all ui-* repositories.)
  2. Continue the practice of protecting the `en.json` file in the Lokalise-to-GitHub process.
  3. Add a rule in Lokalise to automatically copy the key's value into `en_US` and `en_GB` (and en_CA`?). I think I can set up the same rule mark such keys as to-be-reviewed in Lokalise.
  4. Add `en_US` and `en_GB` to the process of building "folio-snapshot"
  5. Make the `en_US` localization the default for "folio-snapshot" builds.

The first and second are already being done now. The third and fourth seem uncontroversial. What about the fifth?



 Comments   
Comment by Peter Murray [ 10/Sep/18 ]

cc: Jakub Skoczen, Cate Boerema, István Bender

Comment by Cate Boerema (Inactive) [ 11/Sep/18 ]

Zak pointed out to Peter on Slack that there have been tickets to developers to use "Headline Capitalization" rather than "Sentence capitalization" for strings in the UI, and he wondered if this is a task we could put on translators rather than developers.

Interesting, because guidance from UX is that labels should be in sentence case. I suppose there may be some exceptions to that which Zak is referring to.

I worry a bit about leaving the capitalization (of English) to translators. How would we ensure consistency? For other languages, capitalization should be translator-provided, as they have different rules (all nouns are capitalized in German, for example).

I'm going to loop in John Coburn and Filip Jakobsen in case they have thoughts.

Comment by Filip Jakobsen [ 11/Sep/18 ]

Thanks for the comment, Cate Boerema.

We use sentence capitalization throughout FOLIO, meaning the only words capitalized should be the ones that are normally capitalized in writing body text. In English, that means the first word of the sentence and e.g. names of brands or of people. In German that means capitalizing the first word of the sentence or string, as well as all the nouns. The rules for each language should be followed in the respective translation files.

Comment by Peter Murray [ 11/Sep/18 ]

Hmmm – to me that points more in the direction of having translators do it rather than developers; it would all be done in one place.

If I could summarize the proposal in one sentence, it would be to make the `en.json` language files "internal to developers" and we would expect real sites to use `en_US.json` and `en_GB.json` and so forth. Perhaps we could even disable the inclusion of `en.json` in builds so only translator-controlled options would appear to the users?

Comment by Cate Boerema (Inactive) [ 12/Sep/18 ]

Can you help me understand how it works today? Something like this?

  1. UI labels are first created by developers in the en.json
  2. Capitalization in the en.json is what?
  3. The US translation files (en_US.json) are created based on the developers' en.json. Given this, there are no untranslated strings in the US English version of the UI
  4. If another locale has an untranslated string, the system displays what?
Comment by Peter Murray [ 12/Sep/18 ]

#1 is correct – UI keys and labels are created by developers in `en.json`. There is a GitHub webhook which automatically adds new keys into Lokalise on commits to the master branch.

#2: capitalization in `en.json` is done by the developer, and based on comments here it seems like it is a combination of sentence case and title case.

#3: `en_US.json` is not automatically created right now; I'm proposing that we add that as a locale and set it as the default in CI builds. The labels in `en_US.json` would be pre-populated using the values in `en.json` (from the developers). Then Lokalise users would modify labels in `en_US.json` as necessary. Note: if a Lokalise user makes a change to a label in `en.json`, that change is not pushed back into GitHub – the change to `en.json` is silently dropped by the Lokalise-to-GitHub script. Given this proposed scenario, there would be no untranslated `en_US.json` strings in Lokalise.

#4: when Lokalise doesn't have a language-specific translation, Lokalise provides the `en.json` string for the locale file. This is a configurable parameter in the API call that downloads the localization files from Lokalise. The choices are "base language" (the setting being used now), "empty" (use an empty string in the locale file), and "skip" (don't include the key in the locale file).

Comment by Zak Burke [ 04/Dec/18 ]

make the `en.json` language files "internal to developers" and we would expect real sites to use `en_US.json` and `en_GB.json` and so forth. Perhaps we could even disable the inclusion of `en.json` in builds so only translator-controlled options would appear to the users

Agreed.

Comment by Peter Murray [ 09/Jan/19 ]

All of this work is now done. As it turns out, the way the settings are structured, which languages appear is an explicit list, not implicit based on what files are in the translations directory. There is now distinct `en_US` and `en_GB` locale files – both automatically populated from what is initially put in `en.json` – and `en.json` itself isn't used by the front end application.

Also, I corrected some spelling errors in the English locale files along the way.

Comment by Peter Murray [ 28/Feb/19 ]

Given the comments in UICHKIN-50 Closed and elsewhere, I wonder if it is worth the trouble to have the hosted testing environments in `en_US.json` (Lokalise-managed string) versus `en.json` (developer managed strings). It might make sense to ignore the spelling and sentence case errors in favor of being able to more readily test/demo issues and features.

Generated at Thu Feb 08 23:13:38 UTC 2024 using Jira 1001.0.0-SNAPSHOT#100246-sha1:7a5c50119eb0633d306e14180817ddef5e80c75d.