aboutsummaryrefslogtreecommitdiff
path: root/core/text/i18n
diff options
context:
space:
mode:
authorMaurizio M. Gavioli <mmg@vistamaresoft.com>2024-04-14 17:18:08 +0200
committerMaurizio M. Gavioli <mmg@vistamaresoft.com>2024-04-14 17:18:08 +0200
commita0cff82320840e4be6d40cee8a2432645773a53e (patch)
treedbb5b972d03b14f636ef0aa120da8075ee906fc0 /core/text/i18n
parent21969fec612b78d34f14b60ad761a3c37860b36b (diff)
Fix the format of some `doc.odin` files of the `core` library which did not made into the documentation.
`c/frontend/tokenizer`: add proper "Example:" header to demo example code, removed empty lines. `container/bit_array`: moved comment before package; aligned narrative lines to left margin; converted case lines into bulleted lines ("- "); converted individual examples to single-tab-indented preformatted text. `dynlib`: removed "//+build ignore" line; added newline at EOF. `image/netpmb`: converted indented lines of "Reading", "Wrting" and "Some syntax..." into bulleted lists; "Formats" indented lines kept as they are as the preformatted text seems relevant to keep the alignments; doubly indented lines kept as single-indented to keep them different (as the format does not allow for two-level bulleted lists); removed empy lines. `os/os2`: WIP, not modified `sys/info`: removed "//+build ignore" line; converted tab-indented initial description into regular left-margin comment; moved uncommented sample code within the doc comment as an "Example:"; moved simple- and double-tabbed separate comments with sample Windows and macOS outputs within the doc comment as bulleted headlines with preformatted output listings; removed now empty comments and blank lines after the package line. `text/i18n`: removed "//+build ignore" line; moved the pacakge line at the end; de-indented the tab-indented introductory narrative; moved sample code comments into the doc comment as tab-indented code with a proper "Example:" heading; removed "```" MD attempts at code formatting. `text/table`: unindented the comment lines of a descriptive kind; headlines of major subdivisions are marked as bold; kept code samples as tab-indented preformatted text (as there are several of them, the standard "Example:" and "Output:" headings cannot be used) removing the "```" MD attempts at code formatting; removed in-between blank lines.
Diffstat (limited to 'core/text/i18n')
-rw-r--r--core/text/i18n/doc.odin185
1 files changed, 90 insertions, 95 deletions
diff --git a/core/text/i18n/doc.odin b/core/text/i18n/doc.odin
index ef619451e..54bf8b80f 100644
--- a/core/text/i18n/doc.odin
+++ b/core/text/i18n/doc.odin
@@ -1,111 +1,106 @@
-//+build ignore
-package i18n
/*
- The i18n package is flexible and easy to use.
+The `i18n` package is flexible and easy to use.
- It has one call to get a translation: `get`, which the user can alias into something like `T`.
+It has one call to get a translation: `get`, which the user can alias into something like `T`.
- `get`, referred to as `T` here, has a few different signatures.
- All of them will return the key if the entry can't be found in the active translation catalog.
+`get`, referred to as `T` here, has a few different signatures.
+All of them will return the key if the entry can't be found in the active translation catalog.
- - `T(key)` returns the translation of `key`.
- - `T(key, n)` returns a pluralized translation of `key` according to value `n`.
+- `T(key)` returns the translation of `key`.
+- `T(key, n)` returns a pluralized translation of `key` according to value `n`.
- - `T(section, key)` returns the translation of `key` in `section`.
- - `T(section, key, n)` returns a pluralized translation of `key` in `section` according to value `n`.
+- `T(section, key)` returns the translation of `key` in `section`.
+- `T(section, key, n)` returns a pluralized translation of `key` in `section` according to value `n`.
- By default lookup take place in the global `i18n.ACTIVE` catalog for ease of use.
- If you want to override which translation to use, for example in a language preview dialog, you can use the following:
+By default lookup take place in the global `i18n.ACTIVE` catalog for ease of use.
+If you want to override which translation to use, for example in a language preview dialog, you can use the following:
- - `T(key, n, catalog)` returns the pluralized version of `key` from explictly supplied catalog.
- - `T(section, key, n, catalog)` returns the pluralized version of `key` in `section` from explictly supplied catalog.
+- `T(key, n, catalog)` returns the pluralized version of `key` from explictly supplied catalog.
+- `T(section, key, n, catalog)` returns the pluralized version of `key` in `section` from explictly supplied catalog.
- If a catalog has translation contexts or sections, then ommitting it in the above calls looks up in section "".
+If a catalog has translation contexts or sections, then omitting it in the above calls looks up in section "".
- The default pluralization rule is n != 1, which is to say that passing n == 1 (or not passing n) returns the singular form.
- Passing n != 1 returns plural form 1.
+The default pluralization rule is n != 1, which is to say that passing n == 1 (or not passing n) returns the singular form.
+Passing n != 1 returns plural form 1.
- Should a language not conform to this rule, you can pass a pluralizer procedure to the catalog parser.
- This is a procedure that maps an integer to an integer, taking a value and returning which plural slot should be used.
+Should a language not conform to this rule, you can pass a pluralizer procedure to the catalog parser.
+This is a procedure that maps an integer to an integer, taking a value and returning which plural slot should be used.
- You can also assign it to a loaded catalog after parsing, of course.
+You can also assign it to a loaded catalog after parsing, of course.
- Some code examples follow.
-*/
+Example:
-/*
-```cpp
-import "core:fmt"
-import "core:text/i18n"
-
-T :: i18n.get
-
-mo :: proc() {
- using fmt
-
- err: i18n.Error
-
- /*
- Parse MO file and set it as the active translation so we can omit `get`'s "catalog" parameter.
- */
- i18n.ACTIVE, err = i18n.parse_mo(#load("translations/nl_NL.mo"))
- defer i18n.destroy()
-
- if err != .None { return }
-
- /*
- These are in the .MO catalog.
- */
- println("-----")
- println(T(""))
- println("-----")
- println(T("There are 69,105 leaves here."))
- println("-----")
- println(T("Hellope, World!"))
- println("-----")
- // We pass 1 into `T` to get the singular format string, then 1 again into printf.
- printf(T("There is %d leaf.\n", 1), 1)
- // We pass 42 into `T` to get the plural format string, then 42 again into printf.
- printf(T("There is %d leaf.\n", 42), 42)
-
- /*
- This isn't in the translation catalog, so the key is passed back untranslated.
- */
- println("-----")
- println(T("Come visit us on Discord!"))
-}
-
-qt :: proc() {
- using fmt
-
- err: i18n.Error
-
- /*
- Parse QT file and set it as the active translation so we can omit `get`'s "catalog" parameter.
- */
- i18n.ACTIVE, err = i18n.parse_qt(#load("translations/nl_NL-qt-ts.ts"))
- defer i18n.destroy()
-
- if err != .None {
- return
+ import "core:fmt"
+ import "core:text/i18n"
+
+ T :: i18n.get
+
+ mo :: proc() {
+ using fmt
+
+ err: i18n.Error
+
+ /*
+ Parse MO file and set it as the active translation so we can omit `get`'s "catalog" parameter.
+ */
+ i18n.ACTIVE, err = i18n.parse_mo(#load("translations/nl_NL.mo"))
+ defer i18n.destroy()
+
+ if err != .None { return }
+
+ /*
+ These are in the .MO catalog.
+ */
+ println("-----")
+ println(T(""))
+ println("-----")
+ println(T("There are 69,105 leaves here."))
+ println("-----")
+ println(T("Hellope, World!"))
+ println("-----")
+ // We pass 1 into `T` to get the singular format string, then 1 again into printf.
+ printf(T("There is %d leaf.\n", 1), 1)
+ // We pass 42 into `T` to get the plural format string, then 42 again into printf.
+ printf(T("There is %d leaf.\n", 42), 42)
+
+ /*
+ This isn't in the translation catalog, so the key is passed back untranslated.
+ */
+ println("-----")
+ println(T("Come visit us on Discord!"))
}
- /*
- These are in the .TS catalog. As you can see they have sections.
- */
- println("--- Page section ---")
- println("Page:Text for translation =", T("Page", "Text for translation"))
- println("-----")
- println("Page:Also text to translate =", T("Page", "Also text to translate"))
- println("-----")
- println("--- installscript section ---")
- println("installscript:99 bottles of beer on the wall =", T("installscript", "99 bottles of beer on the wall"))
- println("-----")
- println("--- apple_count section ---")
- println("apple_count:%d apple(s) =")
- println("\t 1 =", T("apple_count", "%d apple(s)", 1))
- println("\t 42 =", T("apple_count", "%d apple(s)", 42))
-}
-```
-*/ \ No newline at end of file
+ qt :: proc() {
+ using fmt
+
+ err: i18n.Error
+
+ /*
+ Parse QT file and set it as the active translation so we can omit `get`'s "catalog" parameter.
+ */
+ i18n.ACTIVE, err = i18n.parse_qt(#load("translations/nl_NL-qt-ts.ts"))
+ defer i18n.destroy()
+
+ if err != .None {
+ return
+ }
+
+ /*
+ These are in the .TS catalog. As you can see they have sections.
+ */
+ println("--- Page section ---")
+ println("Page:Text for translation =", T("Page", "Text for translation"))
+ println("-----")
+ println("Page:Also text to translate =", T("Page", "Also text to translate"))
+ println("-----")
+ println("--- installscript section ---")
+ println("installscript:99 bottles of beer on the wall =", T("installscript", "99 bottles of beer on the wall"))
+ println("-----")
+ println("--- apple_count section ---")
+ println("apple_count:%d apple(s) =")
+ println("\t 1 =", T("apple_count", "%d apple(s)", 1))
+ println("\t 42 =", T("apple_count", "%d apple(s)", 42))
+ }
+*/
+package i18n