1340342 - [Suggest] Better l10n structure for KumaScript

Status: RESOLVED WONTFIX

(developer.mozilla.org Graveyard :: KumaScript, enhancement, P2)

Description

[YF (Yang)]

What problem would this feature solve?
======================================
Manual maintenance the translations in KumaScript is hard.

Who has this problem?
=====================
Core contributors to MDN

How do you know that the users identified above have this problem?
==================================================================
See below.

How are the users identified above solving this problem now?
============================================================
If I want to batch improves the translations of a locale, I have to manually find (like "mdn.localString" or "en-US"), copy the 'en-US' string and modify the code, fill translation, as well as add the comma to the previous line, remove the comma from the copyed, as `zh-CN` mostly appears at the last line at the moment (although this is not mandatory).

Do you have any suggestions for solving the problem? Please explain in detail.
==============================================================================
At first I thought the "[propose] Leading commas for Array (like `mdn.localString`)", as "I think it can greatly reduce the burden for manual editing of localized strings bluntly, at least."

And now I hope it is an improved l10n structure, such as adding one "mdn.getString('English str')" to replace the "mdn.localString" and else. This can reduce the scope of the macro and too much of the strings to confuse the essence of the code, including its variable, syntax and 'if', etc.

Is there anything else we should know?
======================================
I would it can be driven by like .po file, automatically generate and publishing, as well as integrated on https://pontoon.mozilla.org/.

The string entity is unnecessary and cumbersome I guess. String splicing and context is a problem, parameterization is probably the best, otherwise it should provide the significant instruction and repo url on Pontoon project, as well as the context of strings.

Comment 1

[John Whitlock [:jwhitlock]]

I think this is a good idea that will take several steps, and may take at least a few months to get started given current development priorities. I also think a KumaScript template testing framework (bug 924958) is higher priority, and would be useful to confirm translations when we do take on this task.

Comment 3

[John Whitlock [:jwhitlock]]

Further comments copied from bug 1364809.

A gettext library such as node-gettext [1] or jed [2] could be added to KumaScript. Translations could be extracted to .po files, and be made available on Pontoon [3] for the MDN localization community to translate.

Macro authors would use gettext-formated English strings in macros. For example, the DeprecatedBadge macro [4] currently looks like:

--- Current ---

var titleAttrValue = mdn.localString({
    "en-US": "This deprecated API should no longer be used, but will probably still work.",
    "fr"   : "Cette API obsolète ne doit plus être utilisée, mais elle peut continuer à fonctionner.",
    "ru"   : "Это устаревшее API больше не должно использоваться, но оно по-прежнему может работать.",
    "ja"   : "これは非推奨 API です。未だ動作しているかも知れませんが、将来的に削除される可能性があります。"
});
var str = mdn.localString({
    "en-US": "Deprecated",
    "fr"   : "Obsolète",
    "ru"   : "Устарел",
    "ja"   : "非推奨"
});
if ($0) {
    %><span title="<%=titleAttrValue%>"><i class="icon-thumbs-down-alt"> </i></span><%
} else {
    %><%-template("SimpleBadge", [str, "deprecatedBadge", titleAttrValue])%><%
}

--- End Current ---

After the change, the English strings are used directly, wrapped with a gettext call:

-- New ---

if ($0) {
    %><span title="<%= gettext("This deprecated API should no longer be used, but will probably still work.") %>">
      <i class="icon-thumbs-down-alt"> </i></span><%
} else {
    %><%-template("SimpleBadge", [gettext("Deprecated"), "deprecatedBadge", titleAttrValue])%><%
}

-- End New --

A periodic process would extract these strings to get text's .po files and commit them to the repo.

Localizers would use the familiar Pontoon interfaces to translate strings in macros.

This bug should just cover the effort in:

* Adding a gettext library
* Creating and documenting the string extraction process
* Setting up a project on Pontoon
* Changing a few sample macros

The community can then take over the process of converting existing macros to use gettext.

[1] https://github.com/DanielBaulig/node-gettext
[2] https://github.com/messageformat/Jed
[3] https://pontoon.mozilla.org/projects/mdn/
[4] https://github.com/mozilla/kumascript/blob/master/macros/DeprecatedBadge.ejs

Comment 4

[John Whitlock [:jwhitlock]]

After some research, the plan is:

* Build the KumaScript Docker image from the Kuma project, which already has locales loaded as a submodule. This will require some changes to the Jenkins configuration
* Write a EJS parser for Babel [1]. This keeps this task in Python, where I'm comfortable, and uses the same string extraction process for all MDN strings.
* Use Jed [2] for gettext-compatible functions. It's well-documented, mature, and popular [3].
* Use po2json [4] to load .po files to Jed's JS object notation, as recommended in the Jed docs
* Use sprintf-js [5] as the interpolating string function. It supports positional and named arguments. The project appears popular, mature, and well-supported.

[1] http://babel.pocoo.org/en/latest/messages.html
[2] http://messageformat.github.io/Jed/
[3] https://github.com/messageformat/Jed
[4] https://github.com/mikeedwards/po2json
[5] https://www.npmjs.com/package/sprintf-js

Comment 5

[[github robot]]

Commits pushed to master at https://github.com/mozilla/kuma

https://github.com/mozilla/kuma/commit/d3c7812a3b13fd5c8ca825c0c068c0e2d11eec0c
bug 1340342: Add make target push-kumascript

Push the kumascript image from the kuma project as well. This should be
done when the kumascript master branch is updated, not when the kuma
master branch is update, so it is not included in make push.

https://github.com/mozilla/kuma/commit/d9c2a82d466109e4215e94c6897dbfe561be01d1
Merge pull request #4362 from jwhitlock/push-ks-1340342

bug 1340342: Add make target push-kumascript

Comment 6

[[github robot]]

Commits pushed to master at https://github.com/mdn/kumascript

https://github.com/mdn/kumascript/commit/18b30f15e5c703fc77720cc18a7ddfca4bc9ebe1
bug 1340342: Build in Jenkins as submodule of kuma

Checkout kumascript branches as a submodule of the kuma project, and use
the kuma make targets to build and push kumascript images. This allows
locales to be included in the images.

https://github.com/mdn/kumascript/commit/e3c227cbef623dda5808c75b10e65fd9d90ce8ac
bug 1340342: Remove unused deis make targets

https://github.com/mdn/kumascript/commit/9aea24a54f6da69834bd1d97755630e4233dd4de
bug 1340342: Move image building to kuma project

In order to include the locales in the kumascript image, build it one
level up in the kuma project.

https://github.com/mdn/kumascript/commit/998d9e539127805742634ef1c850221cf04ca2c7
bug 1340342: Build docker image in TravisCI

Checkout the kuma master branch, add the target kumascript branch as the
submodule, and build the docker image inside kuma.

https://github.com/mdn/kumascript/commit/69e7a25ec95fabbf89206a0c0e13304edabae4e1
Merge pull request #283 from mdn/build-with-locales-1340342

bug 1340342: Build and test kumascript as a submodule of kuma

Comment 7

[BMO Automation]

MDN Web Docs' bug reporting has now moved to GitHub. From now on, please file content bugs at https://github.com/mdn/sprints/issues/ and platform bugs at https://github.com/mdn/kuma/issues/.