Localization-Proposal.md

@@ -68,7 +68,7 @@ in which case the message above could become
 
 This lets you avoid having to repeat the domain within every call to `_()` in the input jax.  (It would also be possible for `TEX.Error()` to call `_()` for you, but see below for information about obtaining the translation data.)
 
-The default domain is `"*"`.
+The default domain is `"_"`.
 
 
 ### Substitutions ###
@@ -163,6 +163,9 @@ The methods in `MathJax.Localization` include:
 <dt>addTranslation(local,domain,def)</dt>
 <dd>Defines (or adds to) the translation data for the given <code>locale</code> and <code>domain</code>.  The <code>def</code> is the definition to be merged with the current translation data (if it exists) or to be used as the complete definition (if not).  The data format is described below.</dd>
 
+<dt>fontFamily()</dt>
+<dd>Get the font-family needed to display text in the selected language.  Returns <code>null</code> if no special font is required.</dd>
+
 </dl>
 
 
@@ -182,7 +185,7 @@ The methods in `MathJax.Localization` include:
 
 ### Translation Data ###
 
-Each language has its own data in the `MathJax.Localization.strings` structure.  This structure holds data about the translation, plus the translated string for each domain.
+Each language has its own data in the `MathJax.Localization.strings` structure.  This structure holds data about the translation, plus the translated strings for each domain.
 
 A typical example might be
 
@@ -198,7 +201,8 @@ A typical example might be
       domains: {
         hub: {
           version: "1.0",
-          file: "http://somecompany.com/MathJax/localization/fr/hub.js",  // optional 
+          file: "http://somecompany.com/MathJax/localization/fr/hub.js",  // optional
+          isLoaded: true,
           strings: {
             fnf: "File '%1' not found",
             fl: ["%1 file loaded","%1 files loaded"],
@@ -208,11 +212,131 @@ A typical example might be
         TeX: {
           ...
         },
-        "*": {
+        "_": {
           ...
         },
         ...
       }
 
+The fields have the following meanings:
+
+<dl>
+
+<dt>version</dt>
+<dd>The version of the translation data.</dd>
+
+<dt>directory</dt>
+<dd>An optional value that can be used to override the directory where the translation files for this language are stored.  The default is to add the locale identifier to the end of `MathJax.Localization.directory`, so the value given in the example above is the default value, and could be omitted.</dd>
+
+<dt>file</dt>
+<dd>The name of the file containing the translation data for this language.  The default is the locale identifier with <code>.js</code> appended, so the value given in the example above is the default value, and could be omitted.</dd>
+
+<dt>isLoaded</dt>
+<dd>This is set to true when MathJax has loaded the data for this language.  Typically, when a language is registered with MathJax, the data file isn't loaded at that point.  It will be loaded when it is first needed, and when that happens, this value is set.</dd>
+
+<dt>font</dt>
+<dd>This is a font-family (or list of font-families) that should be used when text in this language is displayed.  If not present, then no special font is needed.</dd>
+
+<dt>meta</dt>
+<dd>This is an object that contains the meta-data about the translation.  Such information can include the name of the translator, the date of the translation, etc.</dd>
+
+<dt>domains</dt>
+<dd>This is an object that contains the translation strings for this language, grouped by domain.  Each domain has an entry, and its value is an object that contains the translation strings for that domain.  The format is described in more detail below.</dd>
+
+</dl>
+
+
+### Domain Data ###
+
+Each domain for which there are translations has an entry in the locale's `domains` object.  These store the following information:
+
+<dl>
+
+<dt>version</dt>
+<dd>The version of the data for this domain</dd>
+
+<dt>file</dt>
+<dd>If the domain data is stored in a separate file from the rest of the language's data (e.g., a third-party extension that is not stored on the CDN may have translation data that is provied by the thrid-party), this property tells where to obtain the translation data.  In the example above, the data is provided by another company via a complete URL.  The default value is the locale's directory with the domain name appended and <code>.js</code> appended to that.</dd>
+
+<dt>isLoaded</dt>
+<dd>This is set to <code>true</code> when the data file has been loaded.</dd>
+
+<dt>strings</dt>
+<dd>This is an object that contains that actual translated strings.  The keys are the message identifiers described in the section on "Getting a Translated String" above, and the values are the translations, or arrays of translations (see the sections on "Plural Forms" above), or translated HTML snippets (see the section on "HTML Snippets" above).</dd>
+
+</dl>
+
+## Registering a Translation ##
+
+Typically, for languages stored on the CDN, MathJax will register the language with a call like
+
+   MathJax.Localization.addTranslation("fr",null,{});
+
+which will create an `fr` entry in the localization data that will be tied to the `[MathJax]/localization/fr` directory, and the `[MathJax]/localization/fr/fr.js` file.  That directory could contain individual files for the various domains, or the `fr.js` file could contain combined data that includes the most common domains, leaving only the lesser-used domains in separate files.
+
+An example `fr.js` file could be
+
+    MathJax.Localization.addTranslation("fr",null,{
+      version: "1.0",
+      meta: {
+        translator: "Joe Green"
+      },
+      domains: {
+        "_": {},
+        TeX: {},
+        Menu: {}
+      }
+    });
+
+This would declare that there are translation files for the `_`, `TeX`, and `Menu` domains, and that these will be loaded individually from their default file names in the default directory of `[MathJax]/localization/fr`.  Other domains will not be translated unless they register themselves via a command like
+
+    MathJax.Localization.addTranslation("fr","Zoom",{});
+
+in which case the domain's data file will be loaded automatically when needed.
+
+One could preload translation strings by including them in the `fr.js` file:
+
+    MathJax.Localization.addTranslation("fr",null,{
+      version: "1.0",
+      meta: {
+        translator: "Joe Green"
+      },
+      domains: {
+        "_": {
+          isLoaded: true,
+          strings: {
+            'fnf': "Fichier `%1` non trouvé",
+            ...
+          }
+        },
+        TeX: {
+          isLoaded: true,
+          strings: {
+            'mcb': "Accolade de fermeture manquante",
+            ...
+          }
+        },
+        Menu: {}
+      }
+    });
+
+Here the `_` and `TeX` strings are preloaded, while the `Menu` strings will be loaded on demand.
+
+A third party extension could include 
+
+    MathJax.Localization.addTranslation("fr","myExtension",{
+      file: "http://myserver.com/MathJax/localization/myExtension/fr.js"
+    });
+
+to add french translations for the `myExtension` domain (used by the extension) so that they would be obtained from the third-party server when needed.
+
+A third party could provide a translation for a language not covered by the MathJax CDN by using
+
+    MathJax.Localization.addTranslation("kr",null,{
+      directory: "http://mycompany.com/MathJax/localization/kr"
+    });
+
+and providing a `kr.js` file in their `MathJax/localization/kr` directory that defines the details of their translation.  If the Korean (kr) locale is selected, MathJax will load `http://mycompany.com/MathJax/localization/kr/kr.js` and any other domain files when they are needed.
+
 
-## The Translation Files ##
+## The Translation Files ##
\ No newline at end of file