Revise language file naming and uid guidelines

[obuisard]

PR Type

Documentation

---

Description

• Clarify language file naming conventions for guided tours

• Add guidelines for extension-specific tour UIDs

• Provide examples for Patch Tester extension

---

Diagram Walkthrough

flowchart LR
  A["General Tours"] --> B["guidedtours.*.ini"]
  C["Extension Tours"] --> D["com_extension.*.ini"]
  C --> E["mod_module.*.ini"]
  C --> F["plg_group_plugin.*.ini"]
  C --> G["tpl_template.*.ini"]

Loading

File Walkthrough

	Relevant files
Documentation	creating-tours.md Enhanced guided tours language file documentation                docs/general-concepts/guided-tours/creating-tours.md Updated language file naming requirements for guided tours Added section for extension-specific tour guidelines Provided concrete examples using Patch Tester extension Clarified UID requirements for different extension types +22/-2

---

[qodo-code-review]

PR Reviewer Guide 🔍

Here are some key observations to aid the review process:

⏱️ Estimated effort to review: 2 🔵🔵⚪⚪⚪

🧪 No relevant tests

🔒 No security concerns identified

⚡ Recommended focus areas for review Consistency Mixed use of backticks and single quotes for code-like literals (e.g., file prefixes and UID prefixes). Standardize formatting to backticks for consistency and readability. All language files need to start with `guidedtours.` and end with `.ini` or `_steps.ini`. Reminder: the language keys can be anything BUT need to contain GUIDEDTOUR in the key name. This is to allow the tour and step views to properly distinguish what is a language key and what is just regular content. #### Language files inside an extension Language files do not need to be placed into administrator/language/[language]/. You can leave the files inside the extension's file structure. In that case, the tour's uid needs to start with the name of the extension and be followed by the rest of the tour's name. For instance, use the tour's uid: `com_patchtester.configuration-part1` to create a configuration tour (part 1) for the Patch Tester extension. Tour uids need to start with 'com_extensionname.', 'mod_modulename.', 'plg_[group]_pluginname.' or 'tpl_templatename.' to be recognized properly. All language files need to start with 'com_extensionname.', 'mod_modulename.', 'plg_[group]_pluginname.' or 'tpl_templatename.', and end with `.ini` or `_steps.ini`. Naming example The UID uses a hyphen 'configuration-part1' while language files use an underscore 'configuration_part1'. Clarify whether hyphen vs underscore differences are intentional and specify the recommendation. For instance, use the tour's uid: `com_patchtester.configuration-part1` to create a configuration tour (part 1) for the Patch Tester extension. Tour uids need to start with 'com_extensionname.', 'mod_modulename.', 'plg_[group]_pluginname.' or 'tpl_templatename.' to be recognized properly. All language files need to start with 'com_extensionname.', 'mod_modulename.', 'plg_[group]_pluginname.' or 'tpl_templatename.', and end with `.ini` or `_steps.ini`. For instance, following the previous example for the Patch Tester extension, we would have: com_patchtester.configuration_part1.ini com_patchtester.configuration_part1_steps.ini Scope clarity Earlier rule says language files must start with 'guidedtours.' but extension section suggests starting with extension prefixes like 'com_*'. Clarify precedence and whether extension-scoped tours should still include 'guidedtours.'. All language files need to start with `guidedtours.` and end with `.ini` or `_steps.ini`. Reminder: the language keys can be anything BUT need to contain GUIDEDTOUR in the key name. This is to allow the tour and step views to properly distinguish what is a language key and what is just regular content. #### Language files inside an extension Language files do not need to be placed into administrator/language/[language]/. You can leave the files inside the extension's file structure. In that case, the tour's uid needs to start with the name of the extension and be followed by the rest of the tour's name. For instance, use the tour's uid: `com_patchtester.configuration-part1` to create a configuration tour (part 1) for the Patch Tester extension. Tour uids need to start with 'com_extensionname.', 'mod_modulename.', 'plg_[group]_pluginname.' or 'tpl_templatename.' to be recognized properly. All language files need to start with 'com_extensionname.', 'mod_modulename.', 'plg_[group]_pluginname.' or 'tpl_templatename.', and end with `.ini` or `_steps.ini`. For instance, following the previous example for the Patch Tester extension, we would have: com_patchtester.configuration_part1.ini com_patchtester.configuration_part1_steps.ini </details> </td></tr> </table>

[qodo-code-review]

PR Code Suggestions ✨

Explore these optional code suggestions:

Category	Suggestion	Impact
High-level	Resolve naming rule contradictions The documentation introduces conflicting rules by saying all language files must start with "guidedtours." while later requiring extension-prefixed filenames and UIDs; clearly separate and standardize the conventions for "general/core" vs "extension-scoped" tours to match the actual loader behavior. Also make the UID and filename examples consistent (hyphen vs underscore, dot placement) and verify they mirror what the system actually discovers, to avoid implementers creating files that won't be recognized. Examples: docs/general-concepts/guided-tours/creating-tours.md [54-78] All language files need to start with `guidedtours.` and end with `.ini` or `_steps.ini`. Reminder: the language keys can be anything BUT need to contain GUIDEDTOUR in the key name. This is to allow the tour and step views to properly distinguish what is a language key and what is just regular content. #### Language files inside an extension Language files do not need to be placed into administrator/language/[language]/. You can leave the files inside the extension's file structure. In that case, the tour's uid needs to start with the name of the extension and be followed by the rest of the tour's name. ... (clipped 15 lines) Solution Walkthrough: Before: # General rule for ALL files All language files need to start with `guidedtours.` ... #### Language files inside an extension # Rule for extension UIDs Tour uids need to start with 'com_extensionname.', 'mod_modulename.', etc. Example UID: `com_patchtester.configuration-part1` # Rule for extension files (contradicts general rule) All language files need to start with 'com_extensionname.', 'mod_modulename.', etc. Example filename: `com_patchtester.configuration_part1.ini` # (inconsistent with UID example) After: #### General Tours Language files for general tours must start with `guidedtours.` ... #### Extension-specific Tours # Rule for extension UIDs Tour uids must start with 'com_extensionname.', 'mod_modulename.', etc. Example UID: `com_patchtester.configuration-part1` # Rule for extension files Language files must start with the extension prefix, matching the UID. Example filename: `com_patchtester.configuration-part1.ini` # (consistent with UID example) Suggestion importance[1-10]: 9 __ Why: The suggestion correctly identifies a major contradiction in the new documentation regarding file naming conventions and a subtle but important inconsistency in the examples, which undermines the PR's goal of clarification.	High
Possible issue	Clarify naming by storage location This line contradicts the later "inside an extension" guidance and can lead to misnamed files that won't be detected. Clarify the rule based on where the files are stored to avoid breakage. docs/general-concepts/guided-tours/creating-tours.md [54] -All language files need to start with `guidedtours.` and end with `.ini` or `_steps.ini`. +When stored in the global language folder, tour language files must start with `guidedtours.` and end with `.ini` or `_steps.ini`. When bundled inside an extension, they must start with the extension prefix (`com_extensionname.`, `mod_modulename.`, `plg_[group]_pluginname.`, or `tpl_templatename.`) and end with `.ini` or `_steps.ini`. Apply / Chat Suggestion importance[1-10]: 7 __ Why: The suggestion correctly identifies a contradiction between the general rule on line 54 and the extension-specific rule on line 70, improving the documentation's clarity and preventing developer confusion.	Medium
General	Align UID and filename separators The UID example uses a hyphen while the filename examples use an underscore, which is confusing. Use a consistent separator to prevent implementers from mixing patterns. docs/general-concepts/guided-tours/creating-tours.md [64-65] For instance, use the tour's uid: -`com_patchtester.configuration-part1` +`com_patchtester.configuration_part1` Apply / Chat Suggestion importance[1-10]: 5 __ Why: The suggestion correctly points out an inconsistency between the UID example (using a hyphen) and the filename example (using an underscore), which could confuse developers. Aligning them improves documentation clarity.	Low
More

[MrMusic]

Personally, I would appreciate it if 'guidedtours' were included in the file name.
Example: guidedtours_com_joomgallery.welcome_steps.ini or com_joomgallery_guidedtours_com_joomgallery.welcome_steps.ini

[obuisard]

Personally, I would appreciate it if 'guidedtours' were included in the file name. Example: guidedtours_com_joomgallery.welcome_steps.ini or com_joomgallery_guidedtours_com_joomgallery.welcome_steps.ini

@MrMusic we have a meeting tomorrow to address this issue. When I went through the PR again, I realized we could improve this to keep it consistent, so I would anticipate we could also support guidedtours.com_joomgallery.welcome_steps.ini.

[HLeithner]

is this ready?

[j2commerce]

is this ready?

This doc is ready, we will eventually propose a more flexible solution but at this time, the additional comments I made are in line with the working code. Thanks Harald @HLeithner

[HLeithner]

is there a relevant PR number?

[obuisard]

is there a relevant PR number?

The improvements are not developed yet.
This PR here is for a more detailed explanation on how the translations work as implemented in Joomla as of now.