MDN-RFC-002: Localization & reducing the number of KumaScript macros

MDN
#1

Over the time, when the KumaScript macro system wasn’t yet on GitHub, it was far easier to create and edit macros (cf. this page for a definition of macros). This resulted in a large, sometime unmaintained, codebase. In order to refactor, improve macros, the MDN team decided to reduce the number of those macros. I think this especially applies to macros that are/were simple, not largely used and/or purely stylistic.

The issue is that I quite didn’t ask before starting doing those changes and Takahiro Uemura rightfully asked why I was doing this and explained that some macros were relevant for Japanese users.

Discussion

Some of these macros are used for localization purposes and I have started removing them thinking that L10N-macros should be: named in English, shared among locales, largely used to be relevant.

Thus, I would ask the following questions, especially targeted for localization teams on MDN and for the MDN team itself:

  • Should an L10N-macro be shared among locales and must it have an english name/english comments in the code?
  • Among this dashboard, which are the L10N-macros you would keep and why? The current L10n-macros I identify are:
    • {{原語併記}}
    • {{英語版章題}}
    • {{訳注}}
    • {{訳語}}
    • {{Referencia_XLST}}
    • {{languages}}
    • {{localize}}
    • {{TranslationInProgress}}
    • {{wiki.localize}}

For the record, the list of L10N-macros I’ve already removed from the content and deleted on the repo. Should one of these be relevant, please indicate why. If the consensus shows I was wrong and reverting is necessary, I’ll gladly revert my edits.

  • {{翻譯中}}
  • {{Yakuchu}}
  • {{Gengoheiki}}
  • {{MDCProjectPagesTOCJa}}
  • {{ListeDeDiscussion}}
  • {{Comunidade}}
  • {{翻訳中}}
  • {{移行予定}}
  • {{移行}}
  • {{SeznamDiskuzí}}
  • {{PotřebujePřeložit}}
  • {{PředchozíNásledující}}
  • {{討論清單}}
  • {{Dopracuj}}
  • {{traducción}}
  • {{AnteriorSiguiente}}
  • {{Suivant}}

Complements

For the sake of completeness, the following macros are currently used for localizing dashboards, sidebars and compat tables. If they should be removed in the long term (when localization for macros will be on Pontoon or somewhere else), they are still necessary right now (feel free to challenge this view):

  • {{L10n-Common}}
  • {{L10n-CompatTable}}
  • {{L10n-CSS}}
  • {{L10n-HTML}}
  • {{L10n-JavaScript}}
  • {{L10n-SVG}}
  • {{L10nErrors}}
  • {{L10nStatusOverview}}

Links

3 Likes
#2

First of all, I’m not sure about legacy system. So my opinion is just one of Japanese l10n community.
I think {{原語併記}} and {{Gengoheiki}} is the same macro, that add the original(English) word enclosed with parenthesis beside the translated word. Sometime translaters may use wrong word or new technical word looks strange. So we put the original word togetter with these macros, to make sense.

You can use the “translating” flag instead of {{TranslationInProgress}}, {{翻譯中}} and {{翻訳中}} macros now. So I think these one is worth to remove.
(“翻譯中” maybe made by chinese comminity)

I’m not sure about others, so I asked Japanese l10n community.

1 Like
#3

Is it possible to list up the pages, in those, such macros are used?
If it is, it helps to judge it is necessary now on or not.

Before the macro code moved into github,
I remember there is a link available to search in which page(s) the macro is used.

#4

Let’s check each macro definition and usage with
https://developer.mozilla.org/en-US/dashboards/macros

I’ve added some summary about Japanese specific l10n macros in our github issues:

Check and discuss, then write summary here to request sphinx_knight how should we treat them.

#5

This page lists the different macros and link to their code and their usage across en-US pages and “all locales” pages.

Though a current bug affect the counting, one can be sure that a count of “0” indicates that the macro is not directly used in the content. I hope this helps.

#6

dymamis and sphinx_knight, thank you for your reply.
https://developer.mozilla.org/en-US/dashboards/macros
is useful.

Following is just FYI, especially for sphinx_knight.
On the mailing list for Mozilla Japanese Translation team
the discussion is ongoing to decide which macro should be back.

#7

Is this an open mailing list?

#8

This is on the GoogleGroups.
https://groups.google.com/forum/?hl=en#!forum/mozilla-translations-ja

Access setting is:
Anyone can view content.
Anyone can join.
Only members can post.
Only members can view the list of members.

1 Like
#9

@sphinx_knight
Though the github issue and ML thread are discussed in Japanese :sweat_smile:, we are almost getting to the goal.
btw, as I said before, {{原語併記}} and {{Gengoheiki}} is the same macro. Is it possible to make an alias?

#10

There is no such “alias” mechanism, choosing a new name will end up by renaming every macro call across pages (a few hundreds (<500) shouldn’t be a big deal if done progressively).
I would advocate for an English “alias” if possible. Basically, for this one, I’d say “TranslationNote” or something similar.

#11

@Uemmra3 @hmatrjp hi there, did you reach consensus about the macros? :slight_smile: (no rush, just wanted this thread not to be forgotten)

1 Like
#12

@sphinx_knight Thank you for your ping.
During local discussion in the Japanese community, reached consensus for some of L10N-macros you listed above.

Followings are from Japanese community and NOT necessary, should be deleted:

  • {{英語版章題}} includes grave bug, according to the comment in the local discussion.
  • {{翻訳中}}
  • {{移行予定}}
  • {{移行}}
  • {{MDCProjectPagesTOCJa}}

There are 4 or 5 macros more from Japanese in the list, another member or I will comment on them next time:

  • {{原語併記}}, {{Gengoheiki}} : for same purpose
  • {{訳注}}, {{Yakuchu}} : for same purpose
  • {{訳語}}
2 Likes
#13

@sphinx_knight
Sorry for late reply.
As long as alias mechanism is not offered, we have to select one macro name for the same purpose, to reduce the codebase.

{{Gengoheiki}} displays English word with translated word, for example:
macro usage: {{Gengoheiki(“fleur”, “flower”)}}
actual result: fleur(flower)

{{訳語}} is similar but reverse order, for example:
macro usage: {{訳語(“flower”, “fleur”)}}
actual result: flower(fleur)

In my opinion, to share these macro with other locales, to change the macro names to English is best, as you’ve adviced. But it’s still under discussion.

#14

Thanks for your feedback :slight_smile:
Coming from a French background where English terms are sometimes used in jargon, the second form ({{訳語}}) makes a bit more sense to me to add something like (“translation’s note”: ) but this might be locale-specific.

This really is an open idea: do you think both could be somehow combined? Strictly speaking, the output just depends on the arguments’ order. Is the semantic strongly different between 訳語 and Gengoheiki?

#15

Sorry I coundn’t respond for long time.

{{訳語}} and {{言語併記}} can be combind. Maybe renaming to {{OrigAndLocal}} or somewhat is good idea for use in other languages.

Also, {{訳注}} and {{Yakuchu}} should be combind and renamed to {{TranslationNote}}.

1 Like