Translations Tool
From ModulesGarden Wiki
(Difference between revisions)
(→About Translations Tool) |
(→Matching and Replacement Logic) |
||
| (29 intermediate revisions by 2 users not shown) | |||
| Line 4: | Line 4: | ||
=About Translations Tool= | =About Translations Tool= | ||
{| | {| | ||
| − | |style="padding: 10px 0px | + | |style="padding: 10px 0px 30px 0px;"|'''Translations''' tool is an integrated feature designed for seamless, efficient, and user-friendly customization of language files in various capacities. <br/>Its user-friendly design ensures a smooth and efficient process, making it a versatile solution for managing a variety of language file customizations.<br/> |
| − | Use this inbuilt into a ModulesGarden addon module tool to easily prepare translations of the original English files. | + | Use this inbuilt into a ModulesGarden addon module tool to easily prepare translations of the original English files. <br/> |
| − | + | ||
| − | + | ||
| − | + | ''The '''Translations''' tool may '''differ slightly across modules'''. This is due to newly implemented features that may not yet be available in your specific module version.<br/> If you notice any missing options, rest assured, they will most likely be included in the next module update.'' | |
| − | + | ||
| − | + | ||
| − | + | ||
| − | + | ||
| − | + | ||
| − | + | ||
| − | + | ||
|} | |} | ||
| − | + | =Management= | |
{| | {| | ||
|style="padding: 10px 0px 15px 0px;"|The '''Translations''' tool allows quick, easy and intuitive management of language file customizations of any kind. <br/> | |style="padding: 10px 0px 15px 0px;"|The '''Translations''' tool allows quick, easy and intuitive management of language file customizations of any kind. <br/> | ||
| − | Read through the below descriptions to learn how to take the most from this inevitably flexible and helpful tool. | + | Read through the below descriptions to learn how to take the most from this inevitably flexible and helpful tool.<br/> |
|} | |} | ||
{| | {| | ||
|style="padding: 0px 0px 30px 25px;"|[[File:TR_1.png]] | |style="padding: 0px 0px 30px 25px;"|[[File:TR_1.png]] | ||
|} | |} | ||
| − | === | + | ==Module Translations== |
| + | ===Languages=== | ||
{| | {| | ||
|style="padding: 10px 0px 15px 0px;"|Steps to follow to add a new translation of the module files are very simple. On this page you will find all already created translations, if there are any.<br/> | |style="padding: 10px 0px 15px 0px;"|Steps to follow to add a new translation of the module files are very simple. On this page you will find all already created translations, if there are any.<br/> | ||
| Line 69: | Line 63: | ||
|} | |} | ||
| − | ==== | + | ===Missing Elements=== |
| + | {| | ||
| + | |style="padding: 10px 0px 15px 0px;"|The '''Missing Elements''' section lists any untranslated keys that are dynamically discovered during module usage.<br/> | ||
| + | Entries are added here automatically when the module encounters an undefined language string. This includes strings missing from both the main '''english.php''' file and any installed translation packages.<br/> | ||
| + | The system tracks these unresolved strings and displays them in the Missing Elements tab.<br/> | ||
| + | |||
| + | If you notice a missing element that is important for you or your client's daily operations, you can easily provide a translation. Simply click the "+" icon to open the '''Add Missing Element''' modal. | ||
| + | |} | ||
| + | {| | ||
| + | |style="padding: 0px 0px 20px 25px;"|[[File:TR_14.png]] | ||
| + | |} | ||
| + | {| | ||
| + | |style="padding: 0px 0px 20px 0px;"|The key field is auto-filled and read-only. Provide the translated text in the editable area and confirm to save. | ||
| + | |} | ||
| + | {| | ||
| + | |style="padding: 0px 0px 20px 25px;"|[[File:TR_15.png]] | ||
| + | |} | ||
| + | {| | ||
| + | |style="padding: 0px 0px 15px 0px;"|Note: once a missing element is added, it will immediately disappear from the list. It is saved in the database and becomes available for translation in other languages.<br/> | ||
| + | Return to the '''Languages''' section, your English file has just been updated. You can preview and modify the newly added element there. | ||
| + | |} | ||
| + | {| | ||
| + | |style="padding: 0px 0px 20px 25px;"|[[File:TR_15_1.png]] | ||
| + | |} | ||
| + | {| | ||
| + | |style="padding: 0px 0px 20px 25px;"|[[File:TR_15_2.png]] | ||
| + | |} | ||
| + | {| | ||
| + | |style="padding: 0px 0px 30px 0px;"|Update your other language files to include the new element, then provide translations for each target language. | ||
| + | |} | ||
| + | |||
| + | ===Dynamic Translations=== | ||
| + | {| | ||
| + | |style="padding: 10px 0px 15px 0px;"|Some strings returned by APIs are dynamic and unpredictable, for example, error messages with unique codes.<br/> | ||
| + | '''Dynamic Translations'' allow you to define '''regular expression (RegEx) matchers''' that capture such variable content and route it to a predefined translation key. <br/>This makes it possible to translate a wide range of similar but non-identical system messages into consistent, user-friendly outputs. | ||
| + | |} | ||
| + | {| | ||
| + | |style="padding: 0px 0px 20px 25px;"|[[File:TR_16.png]] | ||
| + | |} | ||
| + | {| | ||
| + | |style="padding: 0px 0px 15px 0px;"|Use the Add Dynamic Translation button to define a new translation rule based on a regular expression. Provide: | ||
| + | * A regular expression to match incoming dynamic messages | ||
| + | * A translation in a dedicated language | ||
| + | |} | ||
| + | {| | ||
| + | |style="padding: 0px 0px 20px 25px;"|[[File:TR_17.png]] | ||
| + | |} | ||
| + | {| | ||
| + | |style="padding: 0px 0px 20px 25px;"|[[File:TR_18.png]] | ||
| + | |} | ||
| + | {| | ||
| + | |style="padding: 0px 0px 30px 0px;"|'''Important:'''<br/> | ||
| + | ''If you provided translation in your default language (English), the dedicated translations element will be visible in that language. ''<br/> | ||
| + | ''If no translation exists yet for the static key, it will be listed in the ''Missing Elements'' tab, where you can add the final translated text.'' | ||
| + | |} | ||
| + | |||
| + | ====Matching and Replacement Logic==== | ||
| + | {| | ||
| + | |style="padding: 0px 0px 5px 0px;"| | ||
| + | When a message fails to find a direct match in language files, the system tries to match it against your defined regular expressions. If a match is found: | ||
| + | * The message is redirected to the specified key | ||
| + | * Captured groups from the regex can be reused in the final translation using the syntax <code>:$1</code>, <code>:$2</code>, etc. | ||
| + | |} | ||
| + | {| | ||
| + | |style="padding: 0px 0px 15px 0px;"|'''Example Regular Expressions''' | ||
| + | |||
| + | Use patterns like these to catch common dynamic message formats: | ||
| + | * <code>^Error:\s+(.*)$</code> - matches any error starting with "Error:" and captures the rest | ||
| + | * <code>(container|image) .* not found</code> - matches messages like "container nginx not found" or "image apache not found" | ||
| + | * <code>deployment .* (failed|timed out)</code> - handles deployment-related issues | ||
| + | * <code>Volume "(.+)" (exists|in use)</code> - translates volume-specific errors | ||
| + | * <code>network .* is (already|still) in use</code> - identifies network usage conflicts | ||
| + | |} | ||
| + | {| | ||
| + | |style="padding: 0px 0px 15px 0px;"|'''Tips for writing expressions''' | ||
| + | |||
| + | * Use <code>()</code> for grouping | ||
| + | * Use <code>|</code> for alternation | ||
| + | * Use <code>.*</code> for wildcards | ||
| + | * Use <code>:$group_number</code> in translation as replacement ''(starting from "1", eg. <code>:$1</code>)'' | ||
| + | <br/> | ||
| + | '''''Exemplary output:''''' <br/> | ||
| + | |||
| + | A regex: <code>proxmox error code: (\d*)</code> with a translation: <code>Error from Proxmox. Code: :$1</code> will transform:<br/> | ||
| + | <code>proxmox error code: 001</code> → '''Error from Proxmox. Code: 001''' | ||
| + | |} | ||
| + | {| | ||
| + | |style="padding: 0px 0px 30px 25px;"|[[File:TR_19.png]] | ||
| + | |} | ||
| + | |||
| + | ==Module Updates== | ||
{| | {| | ||
|style="padding: 10px 0px 15px 0px;"|When your module is updated to a newer version, none of your language changes will be overwritten.<br/> Thanks to this tool, you will no longer have to remember to verify changes and manually update the language file.<br/> If any translation requires action, you will be notified about that so as to ensure immediate changes in individual translations. | |style="padding: 10px 0px 15px 0px;"|When your module is updated to a newer version, none of your language changes will be overwritten.<br/> Thanks to this tool, you will no longer have to remember to verify changes and manually update the language file.<br/> If any translation requires action, you will be notified about that so as to ensure immediate changes in individual translations. | ||
| Line 84: | Line 168: | ||
|} | |} | ||
| − | + | ==Additional Actions== | |
{| | {| | ||
|style="padding: 10px 0px 20px 0px;"|'''Translations''' tool offers a few extra features that will help you speed up and facilitate the customization of language files. These are: | |style="padding: 10px 0px 20px 0px;"|'''Translations''' tool offers a few extra features that will help you speed up and facilitate the customization of language files. These are: | ||
| − | * '''Cloning Translation'' | + | * '''Cloning Translation''' |
* '''Importing Translation''' | * '''Importing Translation''' | ||
* '''Exportint Translation''' | * '''Exportint Translation''' | ||
| Line 107: | Line 191: | ||
|} | |} | ||
{| | {| | ||
| − | |style="padding: 0px 0px 20px 0px;"|To export a translation simply select the language you are interested in and save its content as a ''.json'' file on your disk. | + | |style="padding: 0px 0px 20px 0px;"|To export a translation simply select the language you are interested in and save its content as a ''.json'' or ''.php'' file on your disk. |
|} | |} | ||
{| | {| | ||
| Line 115: | Line 199: | ||
=Tips= | =Tips= | ||
{| | {| | ||
| − | |style="padding: 10px 0px 30px 15px;"|'''1. | + | |style="padding: 10px 0px 30px 15px;"|'''1. If the ''Translations'' section looks slightly different in one of your modules, it is most likely because new features are being added gradually.'''<br/> |
| + | Missing options in your version will appear in the next module update. | ||
| + | |} | ||
| + | {| | ||
| + | |||
|} | |} | ||
Latest revision as of 13:20, 29 May 2025
Contents |
[edit] About Translations Tool
| Translations tool is an integrated feature designed for seamless, efficient, and user-friendly customization of language files in various capacities. Its user-friendly design ensures a smooth and efficient process, making it a versatile solution for managing a variety of language file customizations. Use this inbuilt into a ModulesGarden addon module tool to easily prepare translations of the original English files.
|
[edit] Management
| The Translations tool allows quick, easy and intuitive management of language file customizations of any kind. Read through the below descriptions to learn how to take the most from this inevitably flexible and helpful tool. |
|
[edit] Module Translations
[edit] Languages
| Steps to follow to add a new translation of the module files are very simple. On this page you will find all already created translations, if there are any. Press 'Add Translation' to begin. |
|
| A new modal will appear, choose the language for which you aim to prepare the translation. Once confirmed, the language will appear on the list. |
|
| Now you will have to customize the language elements of this translation. Press 'Edit' icon, next to the language. You will be moved to the next section. |
|
| There are automatically loaded all of the elements from the original module language file. You may now change, modify, delete or basically translate every line or just some of them. To manage the single language element, press 'Edit' next to this line. |
|
| In dedicated modal form, customize the content according to your needs. Press confirm to finalize. |
|
| Now the new translated element is ready, repeat the steps for every element you wish to translate, modify or customize in any way you need. Clients and/or admin users using the selected language in their WHMCS will now see the module with the customized langs. |
|
[edit] Missing Elements
| The Missing Elements section lists any untranslated keys that are dynamically discovered during module usage. Entries are added here automatically when the module encounters an undefined language string. This includes strings missing from both the main english.php file and any installed translation packages. If you notice a missing element that is important for you or your client's daily operations, you can easily provide a translation. Simply click the "+" icon to open the Add Missing Element modal. |
|
| The key field is auto-filled and read-only. Provide the translated text in the editable area and confirm to save. |
|
| Note: once a missing element is added, it will immediately disappear from the list. It is saved in the database and becomes available for translation in other languages. Return to the Languages section, your English file has just been updated. You can preview and modify the newly added element there. |
|
|
| Update your other language files to include the new element, then provide translations for each target language. |
[edit] Dynamic Translations
| Some strings returned by APIs are dynamic and unpredictable, for example, error messages with unique codes. 'Dynamic Translations allow you to define regular expression (RegEx) matchers that capture such variable content and route it to a predefined translation key. |
|
Use the Add Dynamic Translation button to define a new translation rule based on a regular expression. Provide:
|
|
|
| Important: If you provided translation in your default language (English), the dedicated translations element will be visible in that language. |
[edit] Matching and Replacement Logic
|
When a message fails to find a direct match in language files, the system tries to match it against your defined regular expressions. If a match is found:
|
| Example Regular Expressions
Use patterns like these to catch common dynamic message formats:
|
Tips for writing expressions
A regex: |
|
[edit] Module Updates
| When your module is updated to a newer version, none of your language changes will be overwritten. Thanks to this tool, you will no longer have to remember to verify changes and manually update the language file. If any translation requires action, you will be notified about that so as to ensure immediate changes in individual translations. |
|
| Press 'Update' icon and the tool will detect if there are any new elements added to the main language file (english.php). If there are any differences, every new line will be displayed in the modal for your knowledge. Press confirm and all new elements will be added to the selected translation. Then you will be able to modify them or translate them to keep the translation updated. |
|
[edit] Additional Actions
Translations tool offers a few extra features that will help you speed up and facilitate the customization of language files. These are:
|
|
| You may clone a translation, that is the customized file content form one language directly to a new one. This feature is helpful when you have no differences, or very few differences between two translations. |
|
| Upload a ready language file from your disk directly to the module. The selected in the 'Target Language' field language will create the content of the uploaded file. This feature is especially helpful if you already use other than default 'english.php' files and wish to use our tool for future updates and management. |
|
| To export a translation simply select the language you are interested in and save its content as a .json or .php file on your disk. |
|
[edit] Tips
| 1. If the Translations section looks slightly different in one of your modules, it is most likely because new features are being added gradually. Missing options in your version will appear in the next module update. |