diff --git a/doc/filters.md b/doc/filters.md index 37d3ebf..58bc98b 100644 --- a/doc/filters.md +++ b/doc/filters.md @@ -1,24 +1,21 @@ # Liquid Filters -MetaGlot renders output files through [Liquid](https://shopify.github.io/liquid/) -templates. The filters MetaGlot provides are grouped by rendering target and -described in this document. +MetaGlot renders output files through [Liquid](https://shopify.github.io/liquid/) templates. The filters MetaGlot provides are grouped by rendering target and described in this document. -The rendering environment runs in strict mode: referencing a variable or a property -that does not exist fails the render. +The rendering environment runs in strict mode: referencing a variable or a property that does not exist fails the render. -## General filters +## General Filters The following filters are available in every rendering. -| Filter | Description | -|--------------|-------------| -| `to_string` | Convert the value to its string representation. | -| `format` | Treat the value as a Python format template and apply `str.format` with the arguments passed to the filter. | +| Filter | Description | +|---|---| +| `to_string` | Convert the value to its string representation. | +| `format` | Treat the value as a Python format template and apply `str.format` with the arguments passed to the filter. | | `to_integer` | Convert the value to an integer. | -| `to_float` | Convert the value to a float. | +| `to_float` | Convert the value to a float. | | `is_integer` | Whether the value can be parsed as an integer. | -| `is_float` | Whether the value can be parsed as a float. | +| `is_float` | Whether the value can be parsed as a float. | Examples: @@ -27,10 +24,10 @@ Examples: {{ "ID: {0}" | format: 1001 }} {% comment %}renders "ID: 1001"{% endcomment %} ``` -## RC filters +## RC Filters The following filters are available only when rendering Windows RC files. -| Filter | Description | -|-------------|-------------| +| Filter | Description | +|---|---| | `rc_escape` | Escapes a string for use inside a double-quoted C-style string literal, such as an RC string table entry: `\` becomes `\\` and `"` becomes `\"`. | diff --git a/doc/manifest.md b/doc/manifest.md index c4d02ad..9ba948b 100644 --- a/doc/manifest.md +++ b/doc/manifest.md @@ -1,33 +1,27 @@ # String Manifest -This document describes how to write a MetaGlot string manifest: the TOML file that -declares the translatable strings of an application's metadata. +This document describes how to write a MetaGlot string manifest: the TOML file that declares the translatable strings of an application's metadata. -The manifest is platform-neutral. It only describes *what* can be translated, not how -translations end up in any particular platform format; MetaGlot reads it to produce -Gettext translation catalogs and to fill platform-native output files. The file must -be encoded in UTF-8. +The manifest is platform-neutral. It only describes *what* can be translated, not how translations end up in any particular platform format; MetaGlot reads it to produce Gettext translation catalogs and to fill platform-native output files. The file must be encoded in UTF-8. -## Top-level fields +## Top-Level Fields -| Field | Type | Description | -|-----------|--------|-------------| -| `version` | int | The manifest format version. Currently `1`; any other value is rejected. | -| `strings` | table | All translatable strings. Each item maps a string entry key to a string entry, see below. | +| Field | Type | Description | +|---|---|---| +| `version` | int | The manifest format version. Currently `1`; any other value is rejected. | +| `strings` | table | All translatable strings. Each item maps a string entry key to a string entry, see below. | -## String entry +## String Entry -| Field | Type | Description | -|-----------|--------|-------------| -| `msgid` | string | Required. The untranslated source string. | +| Field | Type | Description | +|---|---|---| +| `msgid` | string | Required. The untranslated source string. | | `context` | string | Optional. Disambiguates entries that share the same `msgid` but are used differently, mirroring the context (`msgctxt`) mechanism of Gettext. Defaults to empty. | | `comment` | string | Optional. A note for translators explaining where and how the string is used. Defaults to empty. | -The string entry key identifies the entry inside the manifest and in generated -outputs. It must be non-empty; both numeric IDs (e.g. `1000`) and names -(e.g. `file_description`) are acceptable, and numeric IDs are represented as strings. +The string entry key identifies the entry inside the manifest and in generated outputs. It must be non-empty; both numeric IDs (e.g. `1000`) and names (e.g. `file_description`) are acceptable, and numeric IDs are represented as strings. -## Validation rules +## Validation Rules A manifest is rejected when: @@ -64,6 +58,4 @@ msgid = "Example" comment = "Display name of the product." ``` -Note that entries `panel_title` and `file_description` share the same `msgid`. This -is allowed because their `context` values differ; without distinct contexts the -combination would be rejected as ambiguous. +Note that entries `panel_title` and `file_description` share the same `msgid`. This is allowed because their `context` values differ; without distinct contexts the combination would be rejected as ambiguous. diff --git a/doc/rc-render-context.md b/doc/rc-render-context.md index d82a54b..d6e2ef8 100644 --- a/doc/rc-render-context.md +++ b/doc/rc-render-context.md @@ -1,53 +1,35 @@ # RC Render Context -This document describes the data that `metaglot rc render` provides to a user-provided -[Liquid](https://shopify.github.io/liquid/) template when rendering Windows RC files. +This document describes the data that `metaglot rc render` provides to a user-provided [Liquid](https://shopify.github.io/liquid/) template when rendering Windows RC files. -MetaGlot reads templates as UTF-8 and writes the rendered file as UTF-8 (without BOM) -using the system's native line endings. This encoding is a built-in constraint of the -tool and is not configurable. Because the generated file is UTF-8, templates should -declare the encoding with `#pragma code_page(65001)` so that the RC compiler parses -the file correctly (see the `example` folder for a complete sample). +MetaGlot reads templates as UTF-8 and writes the rendered file as UTF-8 (without BOM) using the system's native line endings. This encoding is a built-in constraint of the tool and is not configurable. Because the generated file is UTF-8, templates should declare the encoding with `#pragma code_page(65001)` so that the RC compiler parses the file correctly (see the `example` folder for a complete sample). -The renderer runs in strict mode: referencing a variable or a property that does not -exist fails the render. +The renderer runs in strict mode: referencing a variable or a property that does not exist fails the render. -## Top-level variables +## Top-Level Variables -| Variable | Type | Description | -|-------------|-------------------|-------------| +| Variable | Type | Description | +|---|---|---| | `languages` | array of language | One entry per language, see below. | -The order of the entries is not guaranteed: they appear in the order their PO files -are matched. The presence of an English entry is not guaranteed either. An English -entry exists only if an English PO file is provided; otherwise it is simply absent, -and templates must handle that themselves (the text of every entry already falls -back to the manifest source string, which is typically English). +The order of the entries is not guaranteed: they appear in the order their PO files are matched. The presence of an English entry is not guaranteed either. An English entry exists only if an English PO file is provided; otherwise it is simply absent, and templates must handle that themselves (the text of every entry already falls back to the manifest source string, which is typically English). -The language of a PO file is resolved from its `Language:` header, falling back to -the file name without extension; only values valid as Gettext `Language` fields are -accepted. Languages without a Windows language mapping, two PO files describing the -same language, and PO entries unknown to the manifest are rejected. Languages -without a country resolve to a neutral language identifier (sublanguage `0x00`), -e.g. `en` resolves to `0x0009`. +The language of a PO file is resolved from its `Language:` header, falling back to the file name without extension; only values valid as Gettext `Language` fields are accepted. Languages without a Windows language mapping, two PO files describing the same language, and PO entries unknown to the manifest are rejected. Languages without a country resolve to a neutral language identifier (sublanguage `0x00`), e.g. `en` resolves to `0x0009`. -## Language object +## Language Object -| Property | Type | Description | -|---------------|--------|-------------| -| `name` | string | The language tag of the PO file, e.g. `en_US`, `zh_CN`. | -| `langid` | string | Windows language identifier in hexadecimal, e.g. `0x0409`. | -| `primary` | string | Windows primary language identifier in hexadecimal, e.g. `0x09`. | +| Property | Type | Description | +|---|---|---| +| `name` | string | The language tag of the PO file, e.g. `en_US`, `zh_CN`. | +| `langid` | string | Windows language identifier in hexadecimal, e.g. `0x0409`. | +| `primary` | string | Windows primary language identifier in hexadecimal, e.g. `0x09`. | | `sublanguage` | string | Windows sublanguage identifier in hexadecimal, e.g. `0x01`. | -| `block_key` | string | Eight hex digits combining `langid` and the Unicode code page, suitable as a `StringFileInfo` block key, e.g. `040904B0`. | -| `code_page` | string | The version resource code page in decimal, always `1200` (Unicode, `0x04B0`). It is fixed by MetaGlot's UTF-8 read/write pipeline and shares its source with `block_key`; templates must not attempt to use another code page. | -| `strings` | mapping of string to string | Maps every manifest entry key to its resolved text, e.g. `lang.strings.file_description`. | +| `block_key` | string | Eight hex digits combining `langid` and the Unicode code page, suitable as a `StringFileInfo` block key, e.g. `040904B0`. | +| `code_page` | string | The version resource code page in decimal, always `1200` (Unicode, `0x04B0`). It is fixed by MetaGlot's UTF-8 read/write pipeline and shares its source with `block_key`; templates must not attempt to use another code page. | +| `strings` | mapping of string to string | Maps every manifest entry key to its resolved text, e.g. `lang.strings.file_description`. | -The resolved text of an entry falls back to the manifest source string when the -entry is untranslated, missing from the PO file, or marked fuzzy. +The resolved text of an entry falls back to the manifest source string when the entry is untranslated, missing from the PO file, or marked fuzzy. ## Filters -All filters described in [filters.md](filters.md) are available when rendering RC -files: the general filters available in every rendering, and the RC filters such -as `rc_escape`. +All filters described in [filters.md](filters.md) are available when rendering RC files: the general filters available in every rendering, and the RC filters such as `rc_escape`.