Support explanation attribute for Android string resources

nikclayton commented 3 months ago

Describe the problem

As far as I can tell -- based on reading https://docs.weblate.org/en/latest/formats.html#format-explanation and https://docs.weblate.org/en/latest/formats.html#format-description -- there's no clear mechanism for adding an explanation for a string's usage to Android string resources.

Describe the solution you would like

Since Android string resources are XML you could define a Weblate specific namespace for Weblate-supported attributes. Then Android string resources could declare this namespace and add Weblate-specific attributes for each string.

For example:

<?xml version="1.0" encoding="utf-8"?>
<resources xmlns:weblate="http://schemas.weblate.org/android/v1">
  <string name="foo" weblate:explanation="Text that would appear as the explanation for this string in the Weblate UI">...</string>
  ...
</resources>

Describe alternatives you have considered

Adding a comment to the string, e.g.,

  <!-- Text that would appear as the explanation for this string in the Weblate UI -->
  <string name="foo">...</string>

is quite fragile; for example, if Android string resources are moved between different Android project modules it's easy for the comments that are "attached" to the string to get lost.

Since XML provides a standardised mechanism for additional metadata to be attached to elements it seems sensible to use that mechanism, instead of inventing new ad-hoc approaches.

Screenshots

No response

Additional context

This is prompted by noticing translation mistakes in my project. For example, I have a string that looks like this in the source language:

<string name="poll_info_format"> <!-- 15 votes • 1 hour left -->  %1$s • %2$s</string>

The comment's to provide additional context to translators for the contents of the two placeholders (exactly what I'd use the explanation for).

In practice I've seen translators inadvertently corrupt this, so for example the translation becomes:

    <string name="poll_info_format">" &lt;!-- 15 votes • 1 hour left --&gt; %1$s • %2$s"<!-- 15 votes • 1 hour left -->
        %1$s • %2$s</string>

(i.e., the comment markers are stripped and the comment becomes visible text in the app's UI)

nijel commented 3 months ago

Have you tested that native Android tools (such as lint) won't have problems with additional attributes?

nikclayton commented 3 months ago

Yes. I've checked:

Attributes with custom namespaces are ignored (but preserved) by the Translation Editor in Android Studio
Android lint doesn't report any issues with additional attributes
There are no errors or warnings when building an app with a string resource file that has attributes with a custom namespace

nijel commented 2 months ago

Sounds good, we're already supporting weblate-flags XML attribute (see https://docs.weblate.org/en/latest/formats.html#translation-flags), but using an XML namespace is definitely a better approach. There already is a repository with JSON schemas at https://github.com/WeblateOrg/weblate_schemas/, this could be added there.

github-actions[bot] commented 2 months ago

This issue has been added to the backlog. It is not scheduled on the Weblate roadmap, but it eventually might be implemented.

In case you need this feature soon, please consider helping or push it by funding the development.

WeblateOrg / weblate