|
|
|
.. contents::
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
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
|
|
|
|
------------------------------------------
|
|
|
|
* examplel 10n/i18n
|
|
|
|
http://codex.wordpress.org/I18n_for_WordPress_Developers
|
|
|
|
* javascript&locales
|
|
|
|
http://stackoverflow.com/questions/673905/best-way-to-determine-users-locale-within-browser
|
|
|
|
http://stackoverflow.com/questions/2678230/how-to-getting-browser-current-locale-preference-using-javascript
|
|
|
|
* Browser language detection
|
|
|
|
http://stackoverflow.com/questions/1043339/javascript-for-detecting-browser-language-preference
|
|
|
|
http://stackoverflow.com/questions/673905/best-way-to-determine-users-locale-within-browser
|
|
|
|
http://blog.mozilla.org/webdev/2011/10/06/i18njs-internationalize-your-javascript-with-a-little-help-from-json-and-the-server/
|
|
|
|
* CSS2 language pseudo-class
|
|
|
|
http://www.w3.org/TR/CSS2/selector.html#lang
|
|
|
|
* Links about localization in general
|
|
|
|
* http://edutechwiki.unige.ch/en/Software_localization
|
|
|
|
* http://translate.sourceforge.net/wiki/guide/start |
|
|
|
\ No newline at end of file |
