before sending a proposal I’d like that we brainstorm a bit about naming our l10n components. Right now we don’t have any standard for naming them and it’s a complete mess.
You can just look at https://l10n.xwiki.org/projects/xwiki-platform/ and see what I mean for “mess”…
First of all there’s several things to consider for this question:
- in a Weblate there’s two names to configure: the component name (https://docs.weblate.org/en/weblate-4.3.2/admin/projects.html#component-name) which can be changed later and the component slug (https://docs.weblate.org/en/weblate-4.3.2/admin/projects.html#component-slug) which cannot be changed and is more a technical name than something useful to translators.
- we can have for the same Maven module different Weblate components: each Weblate component is linked to a single translation resource file. So it’s a bit rare but it happens that in the same repository we have different source files to translate, for example: https://github.com/xwiki/xwiki-platform/tree/master/xwiki-platform-core/xwiki-platform-help/xwiki-platform-help-ui/src/main/resources/XWiki
- when thinking about names for l10n (at least when talking about component names) we should think about how the translators will understand them: it should help us to locate the translations in the project, but IMO it should also help them to understand what the translations will be about
- we current have 4 weblate projects (xwiki-commons, xwiki-rendering, xwiki-platform, xwiki-contrib): the three first projects are all the same since they are all part of XWiki Platform (and XS). It’s different for xwiki-contrib since we have components for various extensions: we need to take that in consideration since the extension name is a big clue for the translators. Also take into account that an extension might have different components, check: https://l10n.xwiki.org/projects/xwiki-contrib/
So to sum up:
- 1 Git repository = 1 weblate project except for xwiki-contrib
- 1 Maven module doesn’t always mean 1 Weblate component
Personally my first move would be to consider two different naming schemes:
- one scheme for xwiki-commons, xwiki-rendering, xwiki-platform
- another scheme for xwiki-contrib
The reason being that IMO we need to display the Extension name for the xwiki-contrib naming scheme.
Now maybe the scheme could take into account the translations format since it impacts the name of the source file. We currently have 3 different translations format:
- Java properties
- XWiki Page with properties
- XWiki Full page
For the first format we generally have the source files with the same name
ApplicationResources.properties (there’s one exception I think with https://github.com/xwiki/xwiki-platform/tree/master/xwiki-platform-tools/xwiki-platform-tool-jetty/xwiki-platform-tool-jetty-listener/src/main/resources/org/xwiki/tools/jetty/listener/). For the second format, file names are generally finishing with
Now for the third format, it’s using with real XWiki documents (not technical ones) so it completely depends on the page.
So IMO the component name should reflect the format used: it would help finding the translation sources for a component and it would help to get an idea where the translations are used.
So I would propose to define a naming scheme like that:
[project if contrib] - [Module full name] - [Suffix based on the format]
And the suffix based on the format would be:
- if Java Properties:
- if XWiki Page with properties:
- if XWiki Full Page:
Page [Name]with the actual name of the page
Annotation UI - Page Properties
Old Core - Java
Help UI - Page XWikiSyntaxClass
ActivityPub Application - ActivityPub UI - Page Properties
Those proposal are for the Component Names, for the slug name, I would reuse also a scheme based on format, such as:
[extension if needed]-[full Maven component]-[suffix based on the format] with same rules without space for the format.
xwiki-platform-annotation-ui-page-properties xwiki-platform-oldcore-java xwiki-platform-help-ui-page-xwikisyntaxclass application-activitypub-activitypub-ui-page-properties
Remember that those slug name would be used only for new components: we cannot rename easily old ones.
That’s just a first proposal to start discussion, let me know what you think about it.