I18n Tutorial
First Steps
If you want to contribute to ClassicPress localization, the very first step is requesting access to Crowdin Enterprise as a translator or generating correct .pot files if you prefer using another software (like Poedit) to localize.
To request access you can:
- comment on this tutorial
- comment on the i18n announcement
- drop a line in the i18n Zulip channel
- send a private message to me (on the forum or Zulip)
You will then be asked for an email address to send your invitation to the project; after accepting the invitation you will be able to login and start translating in Crowdin Enterprise at classicpress.crowdin.com workspace.
To generate correct .pot files:
Use this WP-CLI command on a CP build version (thanks to Viktor, Matt and Patrick for that, reference here):
wp i18n make-pot . v2-c.pot --ignore-domain --exclude=“/wp-content/” --package-name=“ClassicPress 2.0.0”
After translating the .pot files, it is possible to reupload the translated locale to Crowdin by following this tutorial.
Note that since ClassicPress is a string based localization project it is best to upload the translated content in XLIFF format so that Crowdin is able to match it correctly to its source strings.
How to use Crowdin
after logging in to Crowdin Enterprise classicpress.crowdin.com workspace you will be faced with this screen:
you will need to click on VIEW PROJECT to access the screen allowing you to select the locale you need to translate
your dashboard shows all the locales, with the indication of tag warnings, the completion percentage and new strings percentage bar.
Crowdin is set to pretranslate by means of publicly available Translation Memories (from now on referred as TMs) to help make the process faster. If you click the down arrow you will see this:
Here you can see that pre-translation is complete, Crowdsourcing means completely manual translation of strings and Proofreading means that localizers are working on pre-translated strings to approve them.
Clicking on a locale in your dashboard brings you here:
As you can see there are sources and i18n strings for both v1 and v2 of ClassicPress, you have the option to Pre-translate i18n strings (you do not need this since it is enabled project-wide), Download them, Upload the i18n localized strings and Localize them by selecting the correct action in the selector to the right (you will need to select Crowdsourcing first to complete new strings recently added to the project), then Proofread to verify all strings as completed and correct).
Selecting Crowdsourcing brings you here (to translate or proofread you will have to select the destination string by clicking on it and this will make it editable, clicking on the next one will approve and close edits for the one you are leaving but you can go back to editing it by clicking on it again):
To be noted that I selected the option to have the source and destination strings side by side with a sidebar detailing me suggestions and issues, comments and all the paraphernalia regarding each string to the far right in a dedicated column. In the top right corner of the screen there is the setting panel to configure the view to your liking. This setup is similar to the WordPress WeGlot system so if you are familiar with it you will know how to move around.
From there you translate the new strings. That way Crowdin adds them to the list of the ones to Proofread. This results in the translated strings to have only a check mark near them.
The Proofread option is very similar to this and works just the same, only this time approving a string will result in a double check mark that means done and revised and ready for release once the locale is complete:
About TAGS and TAGS WARNINGS
What are Tags?
Tags are the way Crowdin recognizes formatting, special characters, functions, links and other notable elements inside the strings. There is a Start Tag and End Tag that affect what is placed within them. Every CAT tool like Crowdin use Tags, generally they are “universal” so that files sourced from one software can be uploaded to another, translated and re-uploaded back with no issue or data loss.
What are Tag Warnings and why do they happen?
Sometimes the destination string (especially when Pre-Translated) has misplaced Tags, or not matching Tags with its Source String or missing Tags or a problem with HTML entities encoding. This is a locale-specific issue because sometimes a sentence in a language has a completely different conceptual order in the sentence (for example in en we say “It is” in it we say “Quello è” and the machine translation reads “Quello è” thus generating a Tag Warning because the HTML entity needs proper tags that are NOT PRESENT IN THE SOURCE STRING. That specific error can be corrected simply by removing the HTML entity and relevant Tags and replacing it with “è”).
Another type of Tag Warning can happen when there are hardcoded strings, these cases will have to be evaluated with the help of Core Team because sometimes there is a reason for them being hardcoded.
How to correct them?
Each and every Tag Warning comes with an explanation for it highlighted in color under the destination string. The explanation will point you towards the correct way to solve the issue for your specific locale.
In some cases you can mass solve a specific error (like the one I described in previous paragraph with HTML entities) but it is preferable to be careful with mass solving them because it could lead to some strings being approved without actually revising them.
If in doubt on how to proceed, leave the string be without approving it and refer to the paragraph below.
What to do when in doubt?
When in doubt, remember you are not the only one contributing to the localization effort! the strings you leave unapproved will be taken over by other contributors that will know what to do and will have a chance to help too.
It’s not a race, it’s not a competition, it’s a joint effort!
You can always discuss your doubts about unclear Tag Warnings in the forums or in i18n Zulip channel, this will help the I18n Team to normalize Tags for all locales and will foster healthy debate around localization.
Thanks for being part of the I18n Team!