aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorFlorian Dold <florian@dold.me>2021-03-18 13:56:20 +0100
committerFlorian Dold <florian@dold.me>2021-03-18 13:56:20 +0100
commit43fabc0d1de4b3efe27233479bb4ed08429c4517 (patch)
tree00e1bd71d5b8109db15c86ee750528590b4cfb92
parent51f2ad9b6dc23bd4a73ef1953fedc654b37e26f0 (diff)
pogen readme
-rw-r--r--packages/pogen/README.md77
1 files changed, 77 insertions, 0 deletions
diff --git a/packages/pogen/README.md b/packages/pogen/README.md
new file mode 100644
index 000000000..af1bab73f
--- /dev/null
+++ b/packages/pogen/README.md
@@ -0,0 +1,77 @@
+# pogen - string extraction for internationalizing TypeScript programs
+
+The ``pogen`` tool extracts internationalizable strings from TypeScript programs.
+
+
+## Invocation and Configuration
+
+The ``pogen`` tool must be called from the root of an NPM package.
+
+The input files are determined from the ``tsconfig.json`` file. All input files inside the package that
+the compiler would use are automatically processed.
+
+Inside ``package.json``, the following configuration options are supported:
+
+```
+{
+
+ // [ ... ]
+
+ "pogen": {
+ // Output location of the pofile (mandatory)
+ "pofile": "...",
+
+ // Calls to plain i18n functions are extracted if they
+ // are imported from this package.
+ "plainI18nPackage": "@gnu-taler/taler-util",
+
+ // Calls to react-style i18n functions are extracted if they
+ // are imported from this package.
+ "reactI18nPackage": "@gnu-taler/preact-i18n",
+ }
+
+}
+```
+
+
+## Syntax
+
+Two flavors of syntax are supported:
+
+Template strings:
+
+```
+import { i18n } from "@gnu-taler/taler-util";
+
+console.log(i18n.str`Hello World`);
+console.log(i18n.str`Hello ${user}`);
+
+console.log(i18n.plural(n, i18n.lazy`I have ${n} apple`, i18n.lazy`I have ${n} apples`));
+```
+
+React components:
+
+```
+
+import {
+ Translate,
+ TranslateSwitch,
+ TranslateSingular,
+ TranslatePlural
+} from "@gnu-taler/preact-i18n";
+
+<Translate>Hello, World</Translate>
+
+// Placeholders are other React elements
+<Translate>Hello, <span className="highlight">{userName}<span></Translate>
+
+// Plain placeholders are not supported, they must be surrounded
+// by an element:
+// WRONG: <Translate>Hello, {userName}</Translate>
+
+<TranslateSwitch n={numApples}>
+ <TranslateSingular>I have <span>{n}</span> apple</TranslateSingular>
+ <TranslatePlural>I have <span>{n}</span> apple</TranslatePlural>
+</TranslateSwitch>
+
+```