Naming l10n components

Development
1

Hi everyone,

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 XWiki Platform @ Weblate XWiki.org and see what I mean for “mess”…

First of all there’s several things to consider for this question:

  1. in a Weblate there’s two names to configure: the component name (Translation projects — Weblate 4.3.2 documentation) which can be changed later and the component slug (Translation projects — Weblate 4.3.2 documentation) which cannot be changed and is more a technical name than something useful to translators.
  2. 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: xwiki-platform/xwiki-platform-core/xwiki-platform-help/xwiki-platform-help-ui/src/main/resources/XWiki at master · xwiki/xwiki-platform · GitHub
  3. 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
  4. 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: XWiki Contrib @ Weblate XWiki.org

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 xwiki-platform/xwiki-platform-tools/xwiki-platform-tool-jetty/xwiki-platform-tool-jetty-listener/src/main/resources/org/xwiki/tools/jetty/listener at master · xwiki/xwiki-platform · GitHub). For the second format, file names are generally finishing with Translations.xml.
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: Java
  • if XWiki Page with properties: Page Properties
  • if XWiki Full Page: Page [Name] with the actual name of the page

So for xwiki-platform/xwiki-platform-core/xwiki-platform-annotation/xwiki-platform-annotation-ui/src/main/resources/AnnotationCode/Translations.xml at master · xwiki/xwiki-platform · GitHub we would have:

Annotation UI - Page Properties

For xwiki-platform/xwiki-platform-core/xwiki-platform-oldcore/src/main/resources/ApplicationResources.properties at master · xwiki/xwiki-platform · GitHub we would have:

Old Core - Java

For xwiki-platform/xwiki-platform-core/xwiki-platform-help/xwiki-platform-help-ui/src/main/resources/XWiki/XWikiSyntaxClass.xml at master · xwiki/xwiki-platform · GitHub

Help UI - Page XWikiSyntaxClass

For application-activitypub/activitypub-ui/src/main/resources/ActivityPub/ActivityPubTranslations.xml at master · xwiki-contrib/application-activitypub · GitHub

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.
So:

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.

2

IIRC, the slug name is automatically derived from the component name by Weblate when filling the form. Another solution could be to let the auto completion as is.

Anyway, +1
Thanks!

3

That part sounds good.

Of course an alternative is to create a project per project/repository instead of having all contrib projects mixed.

Not sure for those. I’m wondering if it would not be better to simply put the page reference when it’s a wiki page (whatever kind of wiki page).

I would use a different separator than - to make more clear where each part (most of which already use - a lot) are. From what I understand (“Component name suitable for URLs.”) _ and ~ are possible choices.

4

Same. Moreover, you can have a “Properties” page, so it’s not clear when looking at the component name if “Properties” is the name of the page or the translation format.

+1 also.