diff options
Diffstat (limited to 'doc/development/i18n/externalization.md')
-rw-r--r-- | doc/development/i18n/externalization.md | 63 |
1 files changed, 62 insertions, 1 deletions
diff --git a/doc/development/i18n/externalization.md b/doc/development/i18n/externalization.md index 53825f0904a..52a7f839286 100644 --- a/doc/development/i18n/externalization.md +++ b/doc/development/i18n/externalization.md @@ -137,7 +137,7 @@ The `~/locale` module exports the following key functions for externalization: - `s__()` (namespaced double underscore parenthesis) - `__()` Mark content for translation (note the double underscore). - `s__()` Mark namespaced content for translation -- `n__()` Mark pluralized content for translation +- `n__()` Mark pluralized content for translation ```javascript import { __, s__, n__ } from '~/locale'; @@ -171,6 +171,45 @@ If you need to translate strings in the Vue component's JavaScript, you can impo To test Vue translations, learn about [manually testing translations from the UI](#manually-test-translations-from-the-ui). +### Test files + +Test expectations against externalized contents should not be hard coded, +because we may need to run the tests with non-default locale, and tests with +hard coded contents will fail. + +This means any expectations against externalized contents should call the +same externalizing method to match the translation. + +Bad: + +```ruby +click_button 'Submit review' + +expect(rendered).to have_content('Thank you for your feedback!') +``` + +Good: + +```ruby +click_button _('Submit review') + +expect(rendered).to have_content(_('Thank you for your feedback!')) +``` + +This includes JavaScript tests: + +Bad: + +```javascript +expect(findUpdateIgnoreStatusButton().text()).toBe('Ignore'); +``` + +Good: + +```javascript +expect(findUpdateIgnoreStatusButton().text()).toBe(__('Ignore')); +``` + #### Recommendations If strings are reused throughout a component, it can be useful to define these strings as variables. We recommend defining an `i18n` property on the component's `$options` object. If there is a mixture of many-use and single-use strings in the component, consider using this approach to create a local [Single Source of Truth](https://about.gitlab.com/handbook/values/#single-source-of-truth) for externalized strings. @@ -751,6 +790,28 @@ translate correctly if you extract individual words from the sentence. When in doubt, try to follow the best practices described in this [Mozilla Developer documentation](https://developer.mozilla.org/en-US/docs/Mozilla/Localization/Localization_content_best_practices#Splitting). +### Always pass string literals to the translation helpers + +The `bin/rake gettext:regenerate` script parses the codebase and extracts all the strings from the +[translation helpers](#preparing-a-page-for-translation) ready to be translated. + +The script cannot resolve the strings if they are passed as variables or function calls. Therefore, +make sure to always pass string literals to the helpers. + +```javascript +// Good +__('Some label'); +s__('Namespace', 'Label'); +s__('Namespace|Label'); +n__('%d apple', '%d apples', appleCount); + +// Bad +__(LABEL); +s__(getLabel()); +s__(NAMESPACE, LABEL); +n__(LABEL_SINGULAR, LABEL_PLURAL, appleCount); +``` + ## Updating the PO files with the new content Now that the new content is marked for translation, run this command to update the |