This add-on requires you to have the multilingual (Internationalization) add-on installed.
You also need to have the mbstring PHP extension enabled on your system.
After installation, you should make sure that all your translation folders are BOTH readable and writable by the server process:
If you don't allow reading and writing to these folders some of the basic functionality will not work!
If some of your permissions settings are not correct you will get the following error message when adding or saving a translation:
An unexpected error occurred. Cannot write to file, check permissions
For further info, please check up the question addressing this problem in the FAQ-section.
Different entities in concrete5 context can be translated because of which the translation interfaces have been separated into these entities. This makes managing different level of translations easier and also e.g. makes it so that your package translations travel together with your package. These entities are:
Parsing the source method does multiple thing you don’t have to worry about to keep all your translations consistent. How the process works is as follows:
These phases are specific to your translation context, site, system or selected package and will not affect any other translation contexts.
This all happens through AJAX calls so that the whole process is split into smaller parts. This is because your server might otherwise time out during the process if parsing through big translation entities, such as the system context.
For big translation contexts, such as the system context, this process might take few minutes. It is suggested to run the parsing to concrete5 system context only once per released version number, you really don’t have to do this more often.
THIS PROCESS SHOULD NOT BE CANCELLED AFTER STARTING IT OTHERWISE YOUR TRANSLATION FUNCTIONALITY TO THAT CONTEXT MIGHT BEHAVE IN A QUITE FUNKY WAY!
You can reach the translation interface by clicking “Edit” next to some language in some translation context. After clicking that button you can see a list of all the strings inside this translation and you can start translating by clicking a row from the list, writing the translation for the selected string and then clicking the “Save Translation” or “Next” button.
When you’re doing translation work for the whole context, you might want to move along to the next translation quickly without touching your mouse. You can do this by clicking “CTRL + ENTER” (CMD + ENTER under Mac) when you have your cursor in the “Translation” text field.
After you’ve translated everything you want to translate, finally you should click the “Save & Export” button on bottom of the view to actually save the translations in concrete5 understandable format. This button saves all your translated string back to .po file format and also converts it to machine understandable .mo format that concrete5 reads.
Always remember to save and export your translation, otherwise the translations are not picked up by concrete5!
If you’re not familiar with translating the concrete5 interface before, you might wonder what some of the terms mean in the interface. These terms are basically specific to .po-translation format which is commonly used for PHP applications.
Actions
In the translation interface you have “Actions”-button on top of the view where you can find some actions you can run for that translation. Currently there is only one translation-specific group action but in the future there might be more.
As mentioned before, this add-on also includes some dynamic texts in your translatable texts that are stored in your database. Please note that these entities are handeled specifically to your translatable context, so e.g. package-specific single page names are not included in your site-specific translations.
Currently the following entities are included:
If we’ve missed something here, feel free to drop us a message on the forums section of this add-on.
THIS FEATURE IS AVAILABLE AS OF VERSION 1.1.3
If your package has some special dynamic strings to translate that your users will be adding, you can dynamically find these strings in your package's controller and include them either in the site-context translations (suggested for user-defined strings) or your package translations. Please, do not duplicate any of the strings listed above in the return array of this method.
To do this, just define this method in your package's controller (/packages/your_package/controller.php):
public function getDynamicTranslatableStrings() { $strings = array(); // TODO: Add your dynamic strings here, it's no use to add any static strings here // For example: $mll = new MyModelList(); foreach ($mll->get() as $myModel) { $strings[] = $myModel->getModelName(); } return $strings; }
If you want to include any dynamic strings in your package translation files, just add the same kind of method in the controller with name "getDynamicTranslatableStringsPackage()".
AS OF VERSION 1.3.1
It is now also possible to define the translation contexts and/or plural formats in the dynamic strings as follows:
public function getDynamicTranslatableStrings() { $strings = array(); // Plural format $strings[] = array('msgid' => "Singular format", 'msgid_plural' => "Plural format"); // Translation context $strings[] = array('msgid' => "Singular format", 'msgctxt' => "TranslationContext"); return $strings; }
In the current version of concrete5, all the dynamic entities do not translate correctly because they are not wrapped into the t() function in the core. There’s not much we can do about this than to provide a patch for this issue.
This is a known bug by many multilingual developers and it is discussed in the bug reporting section of concrete5.5.2.1. We’ve also made a patch to solve this issue for that concrete5 version, and you can find it in that bug thread:
https://marketplace.concretecms.com/developers/bugs/5-5-2-1/fix-that-not-translated-tstrings-please-and-some-nagging/#327206
When developing for concrete5, you should wrap all the texts output from your code for the user inside the t() function that concrete5 uses to translate strings. This also applies to dynamic texts that are common for each language but stored in your database, for example attribute key names.
For strings that contain some dynamic text or dynamic number that changes depending on the attributes, you should use the PHP-format to display the dynamic sections of the translatable text. For example:
To keep the translatable texts in standard and correct format, you should not escape anything in the string you wrap inside the t() function in general. If you need to escape e.g. ' or ", don't do it. Instead, wrap the quotes into the other quotes you don't need to include, for example:
This keeps the translation .po files in standard and correct format so that you will not get any parsing exceptions if opening the .po files in external translation tools. There are exceptions to this tip but if you need to worry about them, you probably know what you're doing.
Sometimes doing translation work you might wonder why some of the newly translated strings are not translating actually although you have saved and exported the translation file. Here are some tips to debug this situation:
My progress bar got stuck during the source parsing!
This might happen if you’re running behind quite slow server. There are settings variables you can change in order to change this but the parsing process is quite heavy so we suggest running it on a server capable of processing requests that might take 5 seconds of time at least, depending on your other concrete5 configuration.
I have existing translations in my languages folder that do not appear in the Translations Manager
If you have added manually translations to your system, site or package context before installing the Translations Manager and they don't appear in the translations lists, you haven't probably allowed your server process to read the languages directory or some of its subdirectories. When using translations manager you should always have provided read and write access for the web server process to access your translation files and directories.
Why do some of my translations show 0% or “Unknown” in the complete column?
This is basically because you might not have translated or opened the translation yet. If the column says “Unknown”, this is because you might have translations added in your different contexts before installing the Translations Manager. You can fix the unknown columns by editing that translation for the first time and for the 0% columns, you need to start translating that language.
I’ve translated everything but the translation is still not 100% complete?
With some languages and translation contexts you might never reach 100% complete percentage. This is count based on how many strings you have that have different msgid and msgstr fields from each other. If these are same for some of your translations, you will never reach 100%. Also, in the dynamic translatable content there might be some strings that you don’t even need to translate because of which you are not in 100%.
Why do I get "Permissions denied" error when adding or saving a translation?
"An unexpected error occurred. Cannot write to file, check permissions"
The reason for this is quite obvious and it's because you have incorrect file permissions for the server to be able write to your translation files. If you've already changed the permissions to these directories to be the correct ones, your server is probably set so that the server process running your site is neither the owner of these directories/files nor in the owner group of these directories/files. The following fix is not suggested (explained below why) but it will TEMPORARILY fix this problem. Add this to your config/site.php:
define('DIRECTORY_PERMISSIONS_MODE', 0666); define('FILE_PERMISSIONS_MODE', 0666);
Why this is not suggested in production environment is the "devils number 666". This means everyone who has access to your server, will be able to read and write to EACH AND EVERY FILE concrete5 now creates. This is a real security thread especially in shared hosting environments but trying this at least lets you see where the problem is. A more suitable solution to this for a live production environment would be to add the server process user to be in the owner group of these directories and files when they would not be accessible for each and every user that has access to your server.
Parsing the source or saving translations produces HTTP 500 error
It is likely that you do not have the PHP's mbstring extension enabled that this add-on requires. Please check the phpinfo of your server and search for "mbstring" or "Multibyte String". If you cannot find this extension enabled, you will need to enable it.
The installation routine of this add-on should already make sure that this requirement is fulfilled but in case you have moved your site to another server recently, it is possible that this might still happen.
Some .po-files are not in the standard format and produce errors when saving with Poedit.
When opening and saving a .po file generated with Translations Manager into Poedit software, you might get some syntax errors when saving the file. Usually these syntax errors don’t matter, the file is still saved if you want to use Poedit for some reason. This can happen because the original string is not written in correct format by the developer who has wrapped it into the t()-function. For more information check the “notes for concrete5 developers” section of the documentation. If you change these strings into correct format that does not produce errors in Poedit, they will not be translated by concrete5 because they still appear in incorrect format in the PHP source code and the strings are looked up with the incorrect format.