Merge pull request #104 from janezd/multilingual-tech-note

Documentation: add technical details on multilingual translation

docs/configuration.md

@@ -21,7 +21,7 @@ The available options are
 : If set, Trubar will turn strings into f-strings if translation contains braces and adding an f- prefix makes it a syntactically valid string, *unless* the original string already included braces, in which case this may had been a pattern for `str.format`.
 
 `auto-import` (default: none)
-: A string that, if specified, is prepended to the beginning of each source file with translation. The use is described in the section on plural forms.
+: A string that, if specified, is prepended to the beginning of each source file with translation. The auto-import code is inserted at the top of the file, after any doc strings and imports from the future. The use is described in the section on plural forms.
 
 `static-files` (default: none)
 : A path of directory, or a list of paths. whose content is copied into translated sources. See the section on plural forms. This option is overridden by `static` argument in the command line, if given.

docs/multilingual.md

@@ -56,13 +56,15 @@ and the constructor uses these arguments to retrieve the current language from t
 
 ### The actual code
 
-The above description is simplified for clarity. Trubar doesn't replace `"Data Table"` by `tr.m[1651]` but by `tr.m[1651, "Data Table"]`; similarly for f-strings. The second index, `"Data Table"`, is not used and is there only as a comment for any developers checking the translated sources. Translator doesn't load the message table with
+The above description is simplified for clarity. Trubar doesn't replace `"Data Table"` by `tr.m[1651]` but by `tr.m[1651, "Data Table"]`; similarly for f-strings.
+
+The message table is not stored read into a list
 
 ```python
 self.m = json.load(handle)
 ```
 
-but wraps the list into a class `_list`:
+but wrapped into a class `_list` whose `__getitem__` method accepts, but drops, an extra index:
 
 ```python
 self.m = json.load(handle)
@@ -79,4 +81,27 @@ class _list(list):
         return super().__getitem__(item)
 ```
 
-Note again that Trubar doesn't provide this code, but your application would probably use similar code. Find the complete example at [Orange Canvas Core's Github](https://github.com/biolab/orange-canvas-core/blob/master/orangecanvas/localization/__init__.py).
+Note again that Trubar doesn't provide this code, but your application would probably use similar code. Find the complete example at [Orange Canvas Core's Github](https://github.com/biolab/orange-canvas-core/blob/master/orangecanvas/localization/__init__.py).
+
+**Technical note:** the second index, the original string, `"Data Table"`, is not used to provide defaults; these are always available in message tables. The original string serves two other purposes.
+
+- It provides the original for developers that might inspect the translated code.
+- In case of f-strings, it ensures that the names used in the f-string are stored in the function closure and accessible to `compile`. The function
+
+    ```
+    def f():
+        x = 42
+        def g():
+            return f"{x}"
+    ```
+
+    will compile to
+
+    ```
+    def f():
+        x = 42
+        def g():
+            return _tr.e(tr._c(1234, f"{x}"))
+    ```
+
+    where `1234` is the index of the f-string in the message table. Without the original f-string, the name `x` would not be available to `_tr.c`.