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


(Sphinx Knight) #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.


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}}


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}}


(Uemmra3) #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.

(Takeshi Hamasaki) #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.

(dynamis) #4

Let’s check each macro definition and usage with

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.

(Sphinx Knight) #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.

(Takeshi Hamasaki) #6

dymamis and sphinx_knight, thank you for your reply.
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.

(Sphinx Knight) #7

Is this an open mailing list?

(Takeshi Hamasaki) #8

This is on the GoogleGroups.!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.

(Uemmra3) #9

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?

(Sphinx Knight) #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.