From 867cf7ab331f23f3284f893fa5b2df49aa402672 Mon Sep 17 00:00:00 2001 From: Guy Sartorelli <36352093+GuySartorelli@users.noreply.github.com> Date: Fri, 13 Oct 2023 09:32:52 +1300 Subject: [PATCH] DOC Update translation docs (#369) --- en/05_Contributing/07_Translations.md | 136 +++++++----------- en/05_Contributing/08_Translation_Process.md | 141 ------------------- 2 files changed, 47 insertions(+), 230 deletions(-) delete mode 100644 en/05_Contributing/08_Translation_Process.md diff --git a/en/05_Contributing/07_Translations.md b/en/05_Contributing/07_Translations.md index b5ca745d8..cadd6b37e 100644 --- a/en/05_Contributing/07_Translations.md +++ b/en/05_Contributing/07_Translations.md @@ -6,145 +6,103 @@ icon: globe # Contributing Translations -We are always looking for new translators. Even if a specific language already is translated and has an official -maintainer, we can use helping hands in reviewing and updating translations. Important: It is perfectly fine if you -only have time for a partial translation or quick review work - our system accommodates many people collaborating on the -same language. +The content for UI elements (button labels, field titles, etc) and instruction texts shown in the CMS and elsewhere is +stored in yaml and JavaScript files (see [i18n](/developer_guides/i18n)). These get +uploaded to [transifex](https://explore.transifex.com/silverstripe/) to be edited online. -The content for UI elements (button labels, field titles) and instruction texts shown in the CMS and elsewhere is -stored in the PHP code for a module (see [i18n](../developer_guides/i18n)). All content can be extracted as a "language file", and -uploaded to an online translation editor interface. SilverStripe is already translated in over 60 languages, and we're -relying on native speakers to keep these up to date, and of course add new languages. +Silverstripe CMS is already translated in over 60 languages, and we're +relying on native speakers to keep these up to date, and of course add new languages. -Please register a free translator account to get started, even if you just feel like fixing up a few sentences. +Even if a specific language is already translated, we can use helping hands +in reviewing and updating translations. It is perfectly fine if you only have time for a partial translation or quick +review work - our system accommodates many people collaborating on the same language. -## The online translation tool +Please [register a free translator account](https://app.transifex.com/signup/open-source/) to get started, even if you just feel like fixing up a few sentences. -We provide a GUI for translations through [transifex.com](http://transifex.com). If you don't have an account yet, -please follow the links there to sign up. Select a project from the -[list of translatable modules](https://www.transifex.com/accounts/profile/silverstripe/) and start translating online! +## The online translation tool -For all modules listed there, we automatically import new master strings as they get committed to the various code -bases (via a nightly task), so you're always translating on the latest and greatest version. +We provide a GUI for translations through [transifex.com](http://transifex.com). If you don't have an account yet, +please follow the links there to sign up. Select a project from the +[list of translatable modules](https://app.transifex.com/silverstripe/) and start translating online! -You can check the last successful push of the translation master strings in our -[public continuous integration server](http://teamcity.silverstripe.com/viewType.html?buildTypeId=bt112) -(select "log in as guest"). +If you need help learning how to edit translations in transifex, check out [transifex's documentation](https://help.transifex.com/). ## FAQ -### What happened to getlocalization.com? - -We migrated from getlocalization.com to transifex in mid 2013. - ### How do I translate a module not listed on Transifex? -Most modules maintained by SilverStripe are on Transifex. For other modules, have a look in the module README if -there's any specific instructions. If there aren't, you'll need to translate the YAML files directly. If the module is -on github, you can create a fork, edit the files, and send back your pull request all directly on the website -([instructions](https://help.github.com/articles/fork-a-repo)). +If a core or supported module is not listed on Transifex, usually that means it has no strings which _can_ be translated. +If you find a core or supported module which has strings that can be (or should be able to be) translated, please +[raise an issue on GitHub](./issues_and_bugs) for that module. ### How do I translate substituted strings? (e.g. '%s' or '{my-variable}') -You don't have to - if the english master-string reads 'Hello %s', your german translation would be 'Hallo %s'. Strings -prefixed by a percentage-sign are automatically replaced by silverstripe with dynamic content. See -http://php.net/sprintf for details. The newer `{my-variable}` format works the same way, but makes its intent clearer, +You don't have to - if the english master-string reads 'Hello %s', your german translation would be 'Hallo %s'. Strings +prefixed by a percentage-sign are automatically replaced by silverstripe with dynamic content. See +http://php.net/sprintf for details. The newer `{my-variable}` format works the same way, but makes its intent clearer, and allows reordering of placeholders in your translation. ### Do I need to convert special characters (e.g. HTML-entities)? -Special characters (such as german umlauts) need to be entered in their native form. Please don't use HTML-entities -("ä" instead of "ä"). Silverstripe stores and renders most strings in UTF8 (Unicode) format. +Special characters (such as german umlauts) need to be entered in their native form. Please don't use HTML-entities +(use "ä" instead of "`ä`"). Silverstripe stores and renders most strings in UTF8 (Unicode) format. ### How can I check out my translation in the interface? -Currently translated entities are not directly factored into code (for security reasons and release/review-control), so -you can't see them straight away. +Currently translated entities are not directly factored into code (for security reasons and release/review-control), so +you can't see them straight away. -It is strongly encouraged that you check your translation this way, as its a good way to double check your translation -works in the right context. Please use our `[daily-builds](http://www.silverstripe.org/daily-builds/)` for your local -installation, to ensure you're looking at the most up to date interface. See "Download Translations" above to find out -how to retrieve the latest translation files. +If you really want to check your translation out in context before it has been merged into the codebase, you can follow +the instructions in [i18n](/developer_guides/i18n) to add those translations directly to your Silverstripe CMS project. -### Can I change a translation just for one SilverStripe version? +### Can I change a translation just for one Silverstripe CMS version? -While we version control our translation files like all other source code, the online translation tool doesn't have the -same capabilities. A translated string (as identified by its unique "entity name") is assumed to work well in all -releases. If the interface changes in a non-trivial fashion, the new translations required should have new identifiers +While we version control our translation files like all other source code, the online translation tool doesn't have the +same capabilities. A translated string (as identified by its unique "entity name") is assumed to work well in all +releases. If the interface changes in a non-trivial fashion, the new translations required should have new identifiers as well. -Example: We renamed the "Security" menu title to "Users" in our 3.0 release. As it would confuse users of older versions -unnecessarily, we should be using a new entity name for this, and avoid the change propagating to an older SilverStripe -version. - ### How do I change my interface language? -Once you've logged into the CMS, you should see the text "Hi " near the top left, you can click this to edit -your profile ([direct link](http://localhost/admin/myprofile/)). You can then set the "interface language" from a -dropdown which automatically includes all found translations (based on the files in the `/lang` folders). +Once you've logged into the CMS, you should see your name near the top left. You can click this to edit +your profile. You can then set the "interface language" from a dropdown. ### I've found a piece of untranslatable text -It is entirely possible that we missed certain strings in preparing Silverstripe for translation-support. If you're -technically minded, please read [i18n](../developer_guides/i18n) on how to make it translatable. Otherwise just post your findings -to the forum. - -### How do I add my own module? +It is entirely possible that we missed certain strings in preparing Silverstripe for translation-support. If you're +technically minded, please read [i18n](/developer_guides/i18n) on how to make it translatable and [submit a pull request](./code). -Once you've built a translation-enabled module, you can run the "textcollector" on your local installation for this -specific module (see [i18n](../developer_guides/i18n)). This should find all calls to `_t()` in php and template files, and generate -a new lang file with the default locale (path: /lang/en.yml). Upload this file to the online translation -tool, and wait for your translators to do their magic! +Otherwise please [raise a bug report](./issues_and_bugs) so that we can fix it. ### What about right-to-left (RTL) languages (e.g. Arabic)? -SilverStripe doesn't have built-in support for attribute-based RTL-modifications (``). +Silverstripe CMS doesn't have built-in support for attribute-based RTL-modifications (e.g. ``). -We are currently investigating the available options, and are eager to get feedback on your experiences with -translating silverstripe RTL. +If this is something you'd like to implement, we'd be eager to review a [pull request](./code) for it. ### Can I translate/edit the language files in my favorite text editor (on my local installation) -Not for modules managed by transifex.com, including "framework" and "cms. It causes us a lot of work in merging these -files back. Please use the online translation tool for all new and existing translations. +No, because it causes us a lot of work in merging these files back. Please use the online translation tool for all new and existing translations. -### How does my translation get into a SilverStripe release? +### How does my translation get into a Silverstripe CMS release? -Currently this is a manual process of a core team member downloading approved translations and committing them into our +Currently this is a manual process of a core team member downloading approved translations and committing them into our source tree. ### How does my translation get approved, who is the maintainer? -The online translation tool (transifex.com) is designed to be decentralized and collaborative, so there's no strict -approval or review process. Every logged-in user on the system can flag translations, and discuss them with other +The online translation tool (transifex.com) is designed to be decentralized and collaborative, so there's no strict +approval or review process. Every logged-in user on the system can flag translations, and discuss them with other translators. ### I'm seeing lots of duplicated translations, what should I do? -For now, please translate all duplications - sometimes they might be intentional, but mostly the developer just didn't -know their phrase was already translated. Please contact us about any duplicates that might be worth merging. - -### What happened to translate.silverstripe.org? - -This was a custom-built online translation tool serving us well for a couple of years, but started to show its age -(performance and maintainability). It was replaced with transifex.com. All translations from translate.silverstripe.org -were migrated. Unfortunately, the ownership of individual translations couldn't be migrated. - -As the new tool doesn't support the PHP format used in SilverStripe 2.x, this means that we no longer have a working -translation tool for PHP files. Please edit the PHP files directly and [send us pull requests](/contributing). - -This also applies for any modules staying compatible with SilverStripe 2.x. +For now, please translate all duplications - sometimes they might be intentional, but mostly the developer just didn't +know their phrase was already translated. ## Contact -Get in touch with translators on our [community Slack](http://silverstripe.org/slack) - please join the `#translations` -channel. For generic translation and Transifex questions you might like to use -[Stack Overflow](https://stackoverflow.com/search?q=transifex). Alternatively you can start a discussion on +Get in touch with translators on our [community Slack](http://silverstripe.org/slack) - please join the `#translations` +channel. For generic translation and Transifex questions you might like to use +[Stack Overflow](https://stackoverflow.com/search?q=transifex). Alternatively you can start a discussion on [our forum](https://forum.silverstripe.org). - -## Related - - * [i18n](/developer_guides/i18n): Developer-level documentation of Silverstripe's i18n capabilities - * [Translation Process](translation_process): Information about managing translations for the core team and/or module maintainers. - * [translatable](https://github.com/silverstripe/silverstripe-translatable): DataObject-interface powering the website-content translations - * `["Translatable ModelAdmin" module](http://silverstripe.org/translatablemodeladmin-module/)`: An extension which allows translations of DataObjects inside ModelAdmin diff --git a/en/05_Contributing/08_Translation_Process.md b/en/05_Contributing/08_Translation_Process.md deleted file mode 100644 index c430f7b25..000000000 --- a/en/05_Contributing/08_Translation_Process.md +++ /dev/null @@ -1,141 +0,0 @@ ---- -title: Implement Internationalisation -summary: Implement SilverStripe's internationalisation system in your own modules. -icon: globe ---- - -# Implementing Internationalisation - -To find out about how to assist with translating SilverStripe from a user's point of view, see the -[Contributing Translations page](/contributing/translations). - -## Set up your own module for localisation - -### Collecting translatable text - -As a first step, you can automatically collect all translatable text in your module through the `i18nTextCollector` -task. See [i18n](../developer_guides/i18n#collecting-text) for more details. - -### Import master files - -If you don't have an account on transifex.com yet, [create a free account now](https://www.transifex.com/signup/). After -creating a new project, you have to upload the `en.yml` master file as a new "Resource". While you can do this through -the web interface, there's a convenient -[commandline client](https://docs.transifex.com/client/introduction) for this -purpose. In order to use it, set up a new `.tx/config` file in your module folder: - -```yaml -[main] -host = https://www.transifex.com - - -[my-project.master] -file_filter = lang/.yml -source_file = lang/en.yml -source_lang = en -type = YML -``` - -If you don't have existing translations to import, your project is ready to go - simply point translators to the URL, have them -sign up, and they can create languages and translations as required. - -### Import existing translations - -In case you have existing translations in YML format, there's a "New language" option in the web interface. -Alternatively, use the [commandline client](https://docs.transifex.com/client/introduction). - -### Export existing translations - -You can download new translations in YML format through the web interface, but that can get quite tedious for more than -a handful of translations. Again, the [commandline client](https://docs.transifex.com/client/introduction) -provides a more convenient interface here with the `tx pull` command, downloading all translations as a batch. - -### Merge back existing translations - -If you want to backport translations onto release branches, simply run the `tx pull` command on multiple branches. This -assumes you're adhering to the following guidelines: - - - For significantly changed content of an entity, create a new entity key - - For added/removed placeholders, create a new entity - - Run the `i18nTextCollectorTask` with the `merge=true` option to avoid deleting unused entities - (which might still be relevant in older release branches) - -### Converting your language files from 2.4 PHP format to YML - -The conversion from PHP format to YML is taken care of by a module called -[i18n_yml_converter](https://github.com/chillu/i18n_yml_converter). - -## Download Translations from Transifex.com - -We are managing our translations through a tool called [transifex.com](https://www.transifex.com). Most modules are handled -under the "silverstripe" user, see -[list of translatable modules](https://www.transifex.com/user/profile/silverstripe/). - -Translations need to be reviewed before being committed, which is a process that happens roughly once per month. We're -merging back translations into all supported release branches as well as the `master` branch. The following script -should be applied to the oldest release branch, and then merged forward into newer branches: - -```bash -tx pull - -# Manually review changes through git diff, then commit -git add lang/* -git commit -m "Updated translations" -``` - -[notice] -You can download your work right from Transifex in order to speed up the process for your desired language. -[/notice] - -## JavaScript Translations - -SilverStripe also supports translating strings in JavaScript (see [i18n](/developer_guides/i18n)), but there's a -conversion step involved in order to get those translations syncing with Transifex. Our translation files stored in -`mymodule/javascript/lang/*.js` call `ss.i18n.addDictionary()` to add files. - -```js -ss.i18n.addDictionary('de', {'MyNamespace.MyKey': 'My Translation'}); -``` - -But Transifex only accepts structured formats like JSON. - -``` -{'MyNamespace.MyKey': 'My Translation'} -``` - -First of all, you need to create those source files in JSON, and store them in `mymodule/javascript/lang/src/*.js`. In your `.tx/config` you can configure this path as a separate master location. - -```ruby -[main] -host = https://www.transifex.com - -[silverstripe-mymodule.master] -file_filter = lang/.yml -source_file = lang/en.yml -source_lang = en -type = YML - -[silverstripe-mymodule.master-js] -file_filter = javascript/lang/src/.js -source_file = javascript/lang/src/en.js -source_lang = en -type = KEYVALUEJSON -``` - -Then you can upload the source files via a normal `tx push`. Once translations come in, you need to convert the source -files back into the JS files SilverStripe can actually read. This requires an installation of our -[buildtools](https://github.com/silverstripe-archive/silverstripe-buildtools). - -``` -tx pull -(cd .. && phing -Dmodule=mymodule translation-generate-javascript-for-module) -git add javascript/lang/* -git commit -m "Updated javascript translations" -``` - -# Related - - * [i18n](/developer_guides/i18n/): Developer-level documentation of Silverstripe's i18n capabilities - * [Contributing Translations](/contributing/translations): Information for translators looking to contribute translations of the SilverStripe UI. - * [translatable](https://github.com/silverstripe/silverstripe-translatable): DataObject-interface powering the website-content translations - * ["Translatable ModelAdmin" module](https://github.com/silverstripe-archive/silverstripe-translatablemodeladmin): An extension which allows translations of DataObjects inside ModelAdmin