i10n

text/000-i18n.md

@@ -0,0 +1,92 @@
+Feature Name: i18n
+- Start Date: 2015-09-24
+- RFC PR: (leave this empty)
+- Rust Issue: (leave this empty)
+
+# Summary
+
+This RFC proposes to add an internationalization framework to the rust compiler.
+
+#Motivations
+
+With the growth of the number of users of Rust, localizing the compiler output would be a big plus.
+
+#Proposal
+
+We make every user-facing string in the compiler into a key-value pair.
+
+For example, the following string output by the compiler:
+
+```text
+test.rs:2:4: 2:6 error: expected one of `.`, `;`, `}`, or an operator, found `::`
+```
+
+would be created via:
+
+```Rust
+format_lang!("parser.expected_operator", expected, found)
+```
+
+We would store all translations in localization files which would contain key value pairs. For example:
+
+```
+// in english file
+parser.expected_operator = "expected one of {} or an operator, found {}"
+
+// in french file
+parser.expected_operator = "un opérateur ou l'un des symboles suivants était attendu: {}, obtenu: {}"
+```
+
+If no translation is found, the english localization is used.
+
+To use a specific language, one can run rustc as follows:
+
+```Shell
+> rustc --lang fr <other arguments>
+```
+
+##Long diagnostics
+
+For error codes / long diagnostics, we keep a different file format for convenience and instead of statically baking in the string, we do a file lookup. The only difference will be that instead of calling:
+
+```Rust
+span_err!(E0123, format!("error description {}", some_substitution));
+```
+we will write:
+
+```Rust
+span_err!(diagnostics.E0123, some_substitution);
+```
+
+There will be two diagnostics keys for this, the short and long diagnostic.
+
+```
+diagnostics.E0123.short = "error description {}"
+diagnostics.E0123.long = """foo bar baz \
+quux \
+... \
+"""
+```
+
+##Storage of localizations
+
+The localization files should be stored in a folder called i10n, which is part of the rust installation folder. By default, the english files will be there, but if you put the french files there, the option `--lang fr` will work. The folder will look like this:
+
+```
+i10n
+  |
+  |---en
+    |
+    |---diagnostics
+    |---parser
+```
+
+
+##Language pack
+
+The localization files will be exported as compressed files to allow user to download and handle them easily. To install a new package, the following command will be run:
+
+```Shell
+rustc --install-lang fr # downloads an official language pack from the server
+rustc --install-lang fr=pack.zip # a custom pack can be installed this way
+```