Manual icon indicating copy to clipboard operation
Manual copied to clipboard
verified publisher icon joomla

Update multilingual.md

Open ALsJourney opened this issue 1 year ago • 11 comments

User description

Added a way to easily add Language Overrides

PR Type

documentation

Description

  • Added a new section to the multilingual documentation on using language overrides from the backend.
  • Included PHP code examples for translating strings using Joomla's Text class.
  • Provided step-by-step instructions for creating language overrides in Joomla's backend.

Changes walkthrough 📝

Relevant files
Documentation
multilingual.md
Added instructions for language overrides in Joomla           

versioned_docs/version-5.1/general-concepts/multilingual.md

  • Added a section on using language overrides from the backend.
  • Included PHP code snippets for translating strings.
  • Provided instructions for creating language overrides in Joomla.
    		•  +20/-1   

    💡 PR-Agent usage: Comment /help on the PR to get a list of all available PR-Agent tools and their descriptions

    ALsJourney avatar Jul 16 '24 12:07 ALsJourney

    PR Reviewer Guide 🔍

    ⏱️ Estimated effort to review: 1 🔵⚪⚪⚪⚪
    🧪 No relevant tests
    🔒 No security concerns identified
    ⚡ No key issues to review

    qodo-code-review[bot] avatar Jul 16 '24 12:07 qodo-code-review[bot]

    PR Code Suggestions ✨

    CategorySuggestion                                                                                                                                    Score
    Enhancement
    ✅ Provide a detailed guide on creating language overrides in Joomla
    Suggestion Impact:The commit added a more detailed explanation of how to create language overrides in Joomla, including steps to navigate to the Language Overrides section and select the appropriate options, which aligns with the suggestion to provide a step-by-step guide.

    code diff:

    +### Additional Resources
+
+#### Language Overrides
+
+Language overrides allow administrators to customize translations without modifying the core language files. 
+
+This feature can be accessed from the backend under `System > Language Overrides`. Select `Site` for front-end strings and `Administrator` for back-end strings.
+

    It's recommended to provide an example of how to add a new language override in the
    Joomla backend, possibly with screenshots or a step-by-step guide, to make the
    documentation more practical and user-friendly.

    versioned_docs/version-5.1/general-concepts/multilingual.md [22]

    -You can create these constants inside the backend in `System > Language Overrides`. Choose `Site` for text displayed in the Front End, and `Administrator` for strings inside the backend.
+You can create these constants inside the backend in `System > Language Overrides`. Here's how:
+1. Navigate to `System > Language Overrides`.
+2. Select `Site` for front-end text or `Administrator` for backend strings.
+3. Click 'New' and enter the constant and its translation.
+(Consider adding screenshots to enhance this guide.)
    • [ ] Apply this suggestion <!-- /improve --apply_suggestion=0 -->
    Suggestion importance[1-10]: 9

    Why: This suggestion adds practical value by providing a step-by-step guide, making the documentation more user-friendly and actionable.

    		9
    ✅ Add a comment explaining the function of the code snippet
    Suggestion Impact:The commit added a comment explaining the function of the Text::_("MOD_EXAMPLE_HELLO") and Text::_("MOD_EXAMPLE_GOODBYE") code snippets, enhancing understandability.

    code diff:

    +// Usage in PHP code
+echo Text::_("MOD_EXAMPLE_HELLO");  // Outputs: Hello
+
+echo Text::_("MOD_EXAMPLE_GOODBYE");  // Outputs: Goodbye

    Add a brief explanation or comment in the code snippet to describe what
    Text::_("NAME_OF_YOUR_CONSTANT") does, enhancing understandability for readers
    unfamiliar with Joomla or its i18n features.

    versioned_docs/version-5.1/general-concepts/multilingual.md [17]

    +// Outputs the translated string associated with the constant
 <?php echo Text::_("NAME_OF_YOUR_CONSTANT"); ?>
    • [ ] Apply this suggestion <!-- /improve --apply_suggestion=1 -->
    Suggestion importance[1-10]: 8

    Why: Adding a comment to explain what the code does significantly enhances understandability, especially for readers unfamiliar with Joomla or its i18n features.

    		8
    Readability
    ✅ Improve the readability by structuring the content into distinct paragraphs
    Suggestion Impact:The commit improved readability by breaking the text into smaller paragraphs, aligning with the suggestion to separate different concepts.

    code diff:

    -## Using Language Overrides from the Backend
+Joomla provides robust support for multiple languages, allowing developers to create extensions that can be easily translated and used in different languages.
 
-Letting Content Editors edit translations in Joomla is easy.
+### How Joomla Supports Multiple Languages
+
+Joomla differentiates between **installed languages** (languages that the Joomla core or extensions are translated into) and **content languages** (languages that site content can be written in). 
+
+This distinction helps in managing translations more effectively.
+
+#### Language Constants
+
+To handle translations, Joomla uses **language constants**. These constants are defined in language files (`.ini` and `.sys.ini`) and are used throughout the codebase. 
+
+By using **constants**, you can ensure that your extensions are easily translatable.
+
+#### Language Files
+
+**Language files** are simple text files that map language constants to their translations. There are two main types of language files:
+- `.ini` files: Used for **regular translations.**
+- `.sys.ini` files: Used for **installation and system messages.**
+
+Here’s an example of a language file (`en-GB.mod_example.ini`):
+```ini
+MOD_EXAMPLE_HELLO="Hello"
+MOD_EXAMPLE_GOODBYE="Goodbye"
+```
+
+Place it in the `language/en-GB` directory of your extension.
+
+
+### Implementing Multilingual Support in Your Extension
+
+#### Using the `Text` Class
+
+To translate strings within your code, use the `Text` handling class from Joomla.
 
 ```php
 use Joomla\CMS\Language\Text;
+
+// Usage in PHP code
+echo Text::_("MOD_EXAMPLE_HELLO");  // Outputs: Hello
+
+echo Text::_("MOD_EXAMPLE_GOODBYE");  // Outputs: Goodbye

    
</details>


___


**To improve readability and structure, consider breaking the large text block into <br>smaller paragraphs, especially between different concepts like using language <br>overrides and creating them.**

[versioned_docs/version-5.1/general-concepts/multilingual.md [12-17]](https://github.com/joomla/Manual/pull/281/files#diff-d2cab123b48912c785702a3c26a9a1a54c63acd514841304b5a9cd1107a2127bR12-R17)

```diff
-To translate strings to a specific language that you installed, use the Text handling class from Joomla. 
-When you want to use the string inside your code, do this:
+To translate strings to a specific language that you installed, use the Text handling class from Joomla.
+
+When you want to use the translated string inside your code, do this:
 <?php echo Text::_("NAME_OF_YOUR_CONSTANT"); ?>
    • [ ] Apply this suggestion <!-- /improve --apply_suggestion=2 -->
    Suggestion importance[1-10]: 7

    Why: Breaking the text into smaller paragraphs improves readability and helps in better understanding, but it is a minor enhancement.

    		7
    Maintainability
    ✅ Improve the clarity of the constant name in the example code
    Suggestion Impact:The commit replaced the placeholder constant NAME_OF_YOUR_CONSTANT with more descriptive constants like MOD_EXAMPLE_HELLO and MOD_EXAMPLE_GOODBYE, improving clarity.

    code diff:

    +```ini
+MOD_EXAMPLE_HELLO="Hello"
+MOD_EXAMPLE_GOODBYE="Goodbye"
+```
+
+Place it in the `language/en-GB` directory of your extension.
+
+
+### Implementing Multilingual Support in Your Extension
+
+#### Using the `Text` Class
+
+To translate strings within your code, use the `Text` handling class from Joomla.
 
 ```php
 use Joomla\CMS\Language\Text;
+
+// Usage in PHP code
+echo Text::_("MOD_EXAMPLE_HELLO");  // Outputs: Hello
+
+echo Text::_("MOD_EXAMPLE_GOODBYE");  // Outputs: Goodbye

    
</details>


___


**Consider using a more descriptive constant name in the example code to enhance <br>clarity and maintainability. Using a placeholder like <code>NAME_OF_YOUR_CONSTANT</code> might be <br>too generic and could lead to confusion, especially for beginners.**

[versioned_docs/version-5.1/general-concepts/multilingual.md [17]](https://github.com/joomla/Manual/pull/281/files#diff-d2cab123b48912c785702a3c26a9a1a54c63acd514841304b5a9cd1107a2127bR17-R17)

```diff
-<?php echo Text::_("NAME_OF_YOUR_CONSTANT"); ?>
+<?php echo Text::_("YOUR_DESCRIPTIVE_CONSTANT_NAME"); ?>
    • [ ] Apply this suggestion <!-- /improve --apply_suggestion=3 -->
    Suggestion importance[1-10]: 6

    Why: The suggestion to use a more descriptive constant name improves code readability and maintainability, but it is not crucial for understanding the example.

    		6

    qodo-code-review[bot] avatar Jul 16 '24 12:07 qodo-code-review[bot]

    Thanks for your contribution!

    I really don't want to discourage you as a first time contributor, but we would need in this section some explanation about how Joomla handles multiple languages, ie the idea of using "language constants " and then translating them via the .ini and .sys.ini language files using the Text::_ function.

    You could also reference https://manual.joomla.org/docs/building-extensions/install-update/install/manifest#languages which is about including the languages in an extension's manifest file.

    Think about a developer who wanted to find out how Joomla handled multiple languages, and what he/she needed to do in their extension code to align with that. That's what should go in this section.

    Finally, I suggest you remove "Letting Content Editors edit translations in Joomla is easy." It's not very relevant here (and maybe rather debatable too).

    robbiejackson avatar Jul 18 '24 13:07 robbiejackson

    Hey, firstly, thanks for this manual, it really helped me in my job.

    I was working on creating a custom template in tailwindcss in Joomla, so I just stumbled upon the missing contribution. Sorry for not doing it the right way, I kinda did it on the fly on my job :D

    I'm not a Joomla Expert myself, that's why I only did the Language Overrides in this part of the Manual, however I would be interested in learning how to do it separated in files.

    So what you mean is finish the entire page, and add a way to have translations in files in custom components and modules, right?

    Cheers, AL

    ALsJourney avatar Jul 20 '24 12:07 ALsJourney

    The manual is really aimed at developers of Joomla extensions, so it's providing information to developers about how to design and implement components, modules, plugins and templates primarily.

    I would have imagined the multilingual section having something along the following structure

    1. Some introductory / background material about how Joomla supports multiple languages.

    This would describe installed vs content languages, and cover the concept of language constants and .ini and .sys.ini files.

    1. How to build multilingual support into your extension

    Covering manifest files https://manual.joomla.org/docs/building-extensions/install-update/install/manifest#languages and what's in https://manual.joomla.org/docs/building-extensions/modules/module-development-tutorial/step4-languages.

    Components will need a 'language' column in any database table, and filter content to users based on it - https://docs.joomla.org/J3.x:Developing_an_MVC_Component/Using_the_language_filter_facility (although the details of this would be in an updated component development tutorial).

    1. How Joomla Debug utility can help troubleshooting

    Other topics could include the following - but mostly linking out to other sections (some of which haven't been written yet)

    Language Overrides - this is mostly an admin feature, rather than being relevant to developers, and Joomla handles all the complexity on their behalf. But they should be aware of it.

    Language Associations - https://docs.joomla.org/J3.x:Developing_an_MVC_Component/Adding_Associations

    Form Fields - https://manual.joomla.org/docs/general-concepts/forms-fields/standard-fields/language and https://manual.joomla.org/docs/general-concepts/forms-fields/standard-fields/contentlanguage

    robbiejackson avatar Jul 20 '24 19:07 robbiejackson

    Took a while but I hope its better now. cheers

    ALsJourney avatar Aug 05 '24 18:08 ALsJourney

    This is much better - many thanks! Just several comments of a minor nature.

    Could you increase the header levels in your file. Ie change ### to ## and #### to ###.

    That will make it more consistent with other documentation.

    robbiejackson avatar Aug 08 '24 14:08 robbiejackson

    Sure will do that! I have a question, is there someone to write the components documentation?

    I would be interested in doing that since I never really understood it completely, hence why I am asking you, do you have a proper Joomla 4 Component Tutorial / Guide I can orient myself to?

    ALsJourney avatar Aug 09 '24 18:08 ALsJourney

    Personally, I believe that understanding components and how they work together with modules to be the hardest part about joomla.

    I would also offer to do a tutorial on how to write your own template and how to use tailwindcss in Joomla. Let me know your thoughts. Cheers

    ALsJourney avatar Aug 09 '24 18:08 ALsJourney

    That would be great if you were willing to do either a component or a template tutorial.

    In that case, it would be useful if you got connected to the joomla mattermost community at https://joomlacommunity.cloud.mattermost.com

    robbiejackson avatar Aug 12 '24 08:08 robbiejackson

    I registered and got on it with the same name as in my GitHub. What should I do now? ..

    ALsJourney avatar Aug 12 '24 13:08 ALsJourney