Skip to content

Mathjax v2.x potential feature — localization

Jump to bottom
Davide P. Cervone edited this page Aug 22, 2022 · 1 revision

Requirements

MathJax currently uses a number of English language strings in its UI, namely the MathJax Menu and the various messages (processing, error etc). To support global use of MathJax, we plan to implement a full localization of the UI that allows MathJax users to flexibly decide on the locale and allows translators to contribute easily and efficiently.

The implementation should answer the following questions.

  • How does MathJax decide which language to use?
    • How much control should the author have?
    • How much control should the visitor have?
    • Can MathJax automatically decide the language?
    • Can other software communicate preferences to MathJax (e.g., AT software, dynamic l11n code)?
    • What happens when the required language is not available?
  • How do we guarantee availability of international characters?
    • How do we deal with non-roman languages?
    • How do we deal with non-Arabic numerals?
    • How do we deal with vertical writing?
  • Who makes the translation?
    • Do we have enough complexity to need professional translations?
    • how do we communicate to translators what needs to be translate?
  • What languages should we deliver out of the box?
  • How should MathJax extensions be localized?
  • Can we add translations without making a new release?
    • Where can you find translations?
    • Can you provide private translations?
    • How do we encourage giving translation back?
    • Do we allow alternative or additional translations? (say, redirect to tech support)
    • Do we force CDN users to give their translations back?
  • Do we allow style changes in translations (cf. HTML snippets)? (different language, different need)

technical considerations

  • replace all relevant strings by tokens, have service routine look up the string associated with that token & use the result
    • prevents typos breaking translations
    • helps with combined strings (e.g. "File xyz not found").
    • standard approach to l10n -- Fred, Davide have experience from other projects
  • define file format (in particular, for contributions)
    • 1 file per language vs multiple files per language
      • PRO >1 file: modular nature of MathJax, l10n tied to loading of components, efficient, need to handle extension translations anyway
      • PRO 1 file: simplify 3rd party contributions/hosting, (also, size of 1 file still very small)
      • either way make sure people can find them easily -> repository?
    • could build on Tom's extension json
  • define l10n interface, API for extension authors
    • will allow contributions before implementation is complete
  • defensive programming for UI strings added in the future
  • amount of strings: rough estimates (from Davide)
    • largest : TeX input jax -- 50 or so TeX error messages
    • 8 TeX extensions that include error messages.
    • MathML input jax -- 8 error messages
    • MathJax.js itself -- 12 processing messages, file loading/failure messages.
    • HTML-CSS output jax -- 13 messages about font loading.
    • The menu code: menu labels -- dialogs concerning switching renderers -- the about box
    • FontWarnings extension, v1.0-warning dialog
  • some HTML snippets (e.g., the dialog messages about switching renderers).
    • possible solution: translation mechanism could return fullHTML snippet (not just string)
    • translation would include not just the text, but the structure appropriate for that text (e.g., the correct things will be in bold, and so on)
    • security concerns with 3rd party translations?
  • international characters
    • MathJax fonts don't include accented characters etc
    • use mtextFontInherit configuration property -> messages will be displayed in the font used by surrounding text -- which presumably will support the language
    • configure MathJax list of fonts to include fonts that have unkown characters -- better handling outside of an <mtext> context.

how will MathJax be informed about available translations?

  • CDN will include official/tested translations
  • page authors will be able to load translations from elsewhere/local -- also while using CDN (just like configurations now)
  • 3rd party extensions might need 4th party translations
  • should users be able to side-load? If so, how?
    • pages using CDN are not aware of the 3rd-party translations even if browser properly identifies language
    • menu option "Other" -> enter URL // navigate to translation site
    • alternative: proper browser extensions (e.g., Fred’s Firefox extension)

how should the language be chosen?

  • page authors specify in configuration
  • English default & fallback
  • automatic mechanisms for MathJax to determine language
    • most methods without server help unreliable or unclear, see links at the end (browser locales, navigator object, css lang pseudo-class) (T, D)
    • accept-language header
      • js has no direct access to header -> would require server-side helper -> creates lag
      • optional, default off?
      • customers with local server situations (e.g. Sage) could prefer this
    • mathjax-menu-cookie (like choice of renderer now, cf language switching below)

language switching

  • static language switching (i.e., different pages for different languages) is obviously possible for page authors
  • MathJax could support dynamic switching mechanisms to change l10n if page authors provide such features (e.g. l10n.js)
  • adding MathJax language submenu?
    • PRO it is the standard solution after http-headers, helps user when automatic/page-author setup fails, when locales are wrong for user, when display is not working due to missing fonts
    • CON: switching could fail to work as expected (e.g. local fonts issues), menu clutter
    • page-author should be able to (de)activate this menu, restrict language choices?
      • pages with many languages (wikipedia etc) might want this
      • should an already set user choice (cookie) override page author?
      • default on or off?
    • language submenu generated automatically by the client-side script?
    • based on the list of translation files available on the CDN?
    • the translation file shouldn't be loaded by the client until the language is selected in the submenu
    • how reliable is the font situation (cf. international characters above)?

how to let translators know what there is to be translated

  • provide a template file with tokens and original strings
  • what they do: replace the originals with the translations.
  • create tests to ensure all strings in all supported languages were supplied.

miscellanea

  • with new release announce a changelog of dialogs to help people updating the translation.
  • decimal points, names of trigonometric functions
    • MathML leaves this to author (e.g. wikipedia content)
    • TeXinput could do this in theory, but better with author
  • utf8 characters in strings no problem for MathJaxTeX.
  • For RTL languages, the horizontal position of some UI widgets should probably be mirrored too. For example, MathJax's status/message bar should be positioned on the right instead. Compare Mozilla's MathML Start page in [en-US](https://developer.mozilla.org/en-US/docs/Mozilla_MathML_Project/Start) and [ar](https://developer.mozilla.org/ar/docs/Mozilla_MathML_Project/Start).

helpful links

MathJax Wiki

Clone this wiki locally