Add string templates & alias

Author: fakundo

.eslintrc

@@ -22,6 +22,8 @@
     ],
     "react/prefer-stateless-function": 0,
     "react/prop-types": 0,
-    "no-plusplus": 0
+    "no-plusplus": 0,
+    "default-case": 0,
+    "react/jsx-one-expression-per-line": 0
   }
 }

README.md

@@ -3,20 +3,25 @@
 [![npm](https://img.shields.io/npm/v/react-localized.svg)](https://www.npmjs.com/package/react-localized)
 [![npm](https://img.shields.io/npm/v/preact-localized.svg)](https://www.npmjs.com/package/preact-localized)
 
-Internationalization for React and Preact components.
+Complete internationalization tool for React and Preact components.
 
 Features:
-- based on `gettext` format, uses translation `.po` files
 
-- translation strings can be extracted automatically from source files
+- based on [gettext](https://www.gnu.org/software/gettext/manual/gettext.html) format, uses translation `.po` files
+
+- translation strings for `.po` files can be extracted automatically from project source files
 
 - plural forms are supported
 
+- gettext function aliases are supported
+
+- JavaScript string templates are supported
+
 - locale data is extendable, for example by adding date formats, currencies, etc.
 
 - locale data can be separated from the main bundle by using dynamic import
 
-### Component example
+### Basic component example
 
 ```js
 import { useLocales } from 'react-localized' // or from 'preact-localized'
@@ -25,15 +30,21 @@ export default () => {
   const { gettext } = useLocales()
   return (
     <>
-      { gettext('Hello, world!') } // Привет, мир!
+      { gettext('Hello, World!') } // Привет, Мир!
     </>
   )
 }
 ```
 
+### Complex example
+
+[Live demo](http://fakundo.github.io/react-localized/)
+|
+[Source](https://github.com/fakundo/react-localized/tree/master/examples)
+
 ### Installation and usage
 
-#### 1. Use existing `.po` files with translation or generate them from your project source files
+#### 1. Use existing `.po` files with translation messages or generate them from your project source files
 
 To generate `.po` files you can use the extractor CLI tool. Extractor searches your project source files for functions like `gettext`, `ngettext`, etc. Extractor also can update existing `.po` files without erasing existing translations in those files.
 
@@ -47,18 +58,20 @@ react-localized-extractor [options]
 Options:
   --version      Show version number                                   [boolean]
   --help         Show help                                             [boolean]
-  --locales, -l  List of desired locales                      [array] [required]
+  --locales, -l  List of desired locales (comma separated)   [string] [required]
   --source, -s   Source files pattern
-                                [string] [default: "./src/**/*.@(js|ts|jsx|tsx)"]
-  --output, -o   Output path                     [string] [default: "./locales"]
-  --save-pot     Should save .pot file                [boolean] [default: false]
+                               [string] [default: "./src/**/*.@(js|ts|jsx|tsx)"]
+  --output, -o   Output .po files directory      [string] [default: "./locales"]
+  --alias, -a    Function alias                                         [string]
+  --save-pot     Should create catalog .pot file in output directory
+                                                      [boolean] [default: false]
 ```
 
 ```console
-react-localized-extractor -l ru -s ./src/**/*.js -o ./locales
+react-localized-extractor -l ru
 ```
 
-#### 2. Add / edit translation in `.po` files
+#### 2. Modify `.po` files to add / edit translation
 
 Use your favourite editor for `.po` files. I recommend you to use `Poedit`.
 
@@ -91,11 +104,11 @@ npm i react-localized
 npm i preact-localized
 ```
 
-#### 5. Create locale data
+#### 5. Create data object for each locale
 
-Use the second argument for extra data such as date formats, currencies, and so on.
+Use the `createLocale` function from the package. The first argument is for translation messages taken from `.po` file. The second argument is for extra data such as date formats, currencies, and so on.
 
-Example of the file `ru.js`
+Example of the file `ru.js` for russian locale
 
 ```js
 import { createLocale } from 'react-localized' // or from 'preact-localized'
@@ -106,7 +119,7 @@ const extra = { ... }
 export default createLocale(messages, extra)
 ```
 
-##### 6. Render provider
+#### 6. Render provider component
 
 ```js
 import { LocalizedProvider } from 'react-localized' // or from 'preact-localized'
@@ -119,7 +132,10 @@ const ru = () => import('ru.js').then(data => data.default) // separated from th
 const locales = { fr, de, ru }
 
 export default () => (
-  <LocalizedProvider locales={locales} selected="fr">
+  <LocalizedProvider 
+    locales={locales} 
+    selected="fr"
+  >
     { ({ localeReady }) => (
       localeReady 
         ? 'render children' 
@@ -138,10 +154,10 @@ export default () => {
   const { gettext, ngettext, ...extra } = useLocales()
   return (
     <>
-      { gettext('Hello, world!') } // Привет, мир!
-      { ngettext('%s apple', '%s apples', 1, 1) } // 1 яблоко
-      { ngettext('%s apple', '%s apples', 2, 2) } // 2 яблока
-      { ngettext('%s apple', '%s apples', 10, 10) } // 10 яблок
+      { gettext('Hello, World!') } // Привет, Мир!
+      { ngettext('apple', 'apples', 1) } // яблоко
+      { ngettext('apple', 'apples', 2) } // яблока
+      { ngettext('apple', 'apples', 5) } // яблок
     </>
   )
 }
@@ -154,10 +170,9 @@ import { withLocales } from 'react-localized' // or from 'preact-localized'
 
 class LocalizedComponent extends Component {
   render() {
-    const { gettext, pgettext, formatDate, formats } = this.props // 'formatDate' and 'formats' are extra data passed to the 'createLocale'
+    const { pgettext, formatDate, formats } = this.props // 'formatDate' and 'formats' are extra data passed to the 'createLocale'
     return (
       <>
-        { gettext('My name is %s', 'John') } // Мое имя John
         { pgettext('Context', 'Text with context') } // Текст с контекстом
         { formatDate(new Date(), formats.date) } // 1 января 2020
       </>
@@ -167,28 +182,91 @@ class LocalizedComponent extends Component {
 
 export default withLocales()(LocalizedComponent)
 ```
+### Using string templates
 
-### See example
+```js
+import { useLocales } from 'react-localized' // or from 'preact-localized'
 
-[Demo](http://fakundo.github.io/react-localized/)
-|
-[Source](https://github.com/fakundo/react-localized/tree/master/examples)
+export default () => {
+  const { gettext, ngettext, pgettext, npgettext } = useLocales()
+  const name = 'Anna'
+  const i = 2
+  return (
+    <>
+      { gettext`My name is ${name}` } // Мое имя Anna
+      { ngettext`${i} apple``${i} apples`(i) } // 2 яблока
+      { pgettext('Ctx')`My name is ${name}` }
+      { npgettext('Ctx')`${i} apple``${i} apples`(i) }
+    </>
+  )
+}
+```
+
+### Using function aliases
+
+Use `LocalizedProvider` `alias` prop to define function aliases.
+
+Example of alias for `gettext` only
+
+```js
+<LocalizedProvider alias="__" />
+```
+
+Example of aliases for `gettext` and `ngettext`
+
+```js
+<LocalizedProvider alias={{ gettext: '__', ngettext: '__n' }} />
+```
+
+Example of alias usage
+
+```js
+import { useLocales } from 'react-localized' // or from 'preact-localized'
+
+export default () => {
+  const { __, __n } = useLocales()
+  const name = 'Anna'
+  return (
+    <>
+      { __('Hello, World!') }
+      { __`My name is ${name}` }
+      { __n`apple``apples`(5) }
+    </>
+  )
+}
+```
+
+Also configure extractor.
+
+Example of alias for `gettext` only
+
+```console
+react-localized-extractor -l ru -a __
+```
+
+Example of aliases for `gettext` and `ngettext`
+
+```console
+react-localized-extractor -l ru -a.gettext __ -a.ngettext __n
+```
 
 ### API
 
 #### LocalizedProvider props
 
 - `locales` - defined locales
 - `selected` - selected locale (default `en`)
+- `alias` - function aliases (string or object)
 - `children({ localeReady })`
 
 #### Data returned by hook / props passed to the child of the HOC
 
 - `locale`
-- `gettext(input, ...injections)`
-- `ngettext(singular, plural, n, ...injections)`
-- `pgettext(context, input, ...injections)`
-- `npgettext(context, singular, plural, n, ...injections)`
+- `gettext(text)`
+- `ngettext(text, textPlural, n)`
+- `pgettext(context, text)`
+- `npgettext(context, text, textPlural, n)`
+- `...aliases` - defined function aliases
 - `...extra` - extra data passed to the `createLocale`
 
 ### License

examples/locales/en.js

@@ -1,8 +1,8 @@
-import format from 'date-fns/format'
+import formatDate from 'date-fns/format'
 import { createLocale } from 'react-localized'
 
 export default createLocale(null, {
-  formatDate: format,
+  formatDate,
   formats: {
     date: 'MMMM d, yyyy',
   },

examples/locales/index.js

@@ -1,6 +1,8 @@
-import englishData from './en'
+import en from './en'
+// import ru from './ru'
 
 export default {
-  en: englishData,
+  en,
+  // ru,
   ru: () => import('./ru').then((data) => data.default),
 }

examples/locales/ru.js

@@ -1,10 +1,10 @@
-import format from 'date-fns/format'
+import formatDate from 'date-fns/format'
 import locale from 'date-fns/locale/ru'
 import { createLocale } from 'react-localized'
 import messages from './ru.po'
 
 export default createLocale(messages, {
-  formatDate: (date, formatStr) => format(date, formatStr, { locale }),
+  formatDate: (date, formatStr) => formatDate(date, formatStr, { locale }),
   formats: {
     date: 'dd MMMM yyyy',
   },

examples/locales/ru.po

@@ -16,32 +16,56 @@ msgstr ""
 "X-Poedit-SourceCharset: UTF-8\n"
 "X-Poedit-SearchPath-0: .\n"
 
-#: ../../examples/src/DecoratedClassComponent.js:10
-#: ../../examples/src/DecoratedFunctionalComponent.js:7
-#: ../../examples/src/HookedComponent.js:9
-msgid "%s apple"
-msgid_plural "%s apples"
-msgstr[0] "%s яблоко"
-msgstr[1] "%s яблока"
-msgstr[2] "%s яблок"
+#: ../../examples/src/AliasUsingComponent.js:13
+#: ../../examples/src/TemplateUsingComponent.js:13
+msgid "${} apple"
+msgid_plural "${} apples"
+msgstr[0] "${} яблоко"
+msgstr[1] "${} яблока"
+msgstr[2] "${} яблок"
 
+#: ../../examples/src/DecoratedFunctionalComponent.js:12
+#: ../../examples/src/DecoratedFunctionalComponent.js:16
 #: ../../examples/src/DecoratedFunctionalComponent.js:8
-msgid "%s table"
-msgid_plural "%s tables"
-msgstr[0] "%s стол"
-msgstr[1] "%s стола"
-msgstr[2] "%s столов"
+msgid "apple"
+msgid_plural "apples"
+msgstr[0] "яблоко"
+msgstr[1] "яблока"
+msgstr[2] "яблок"
 
 #: ../../examples/src/HookedComponent.js:8
-msgid "Hello, world!"
-msgstr "Привет, мир!"
+msgid "Hello, World!"
+msgstr "Привет, Мир!"
+
+#: ../../examples/src/AliasUsingComponent.js:11
+#: ../../examples/src/TemplateUsingComponent.js:11
+msgid "My name is ${}"
+msgstr "Мое имя ${}"
+
+#: ../../examples/src/AliasUsingComponent.js:14
+#: ../../examples/src/TemplateUsingComponent.js:14
+msgctxt "Context"
+msgid "${} table"
+msgid_plural "${} tables"
+msgstr[0] "${} стол"
+msgstr[1] "${} стола"
+msgstr[2] "${} столов"
 
-#: ../../examples/src/DecoratedClassComponent.js:9
-#: ../../examples/src/DecoratedFunctionalComponent.js:6
-msgid "My name is %s"
-msgstr "Мое имя %s"
+#: ../../examples/src/DecoratedClassComponent.js:13
+msgctxt "Context"
+msgid "table"
+msgid_plural "tables"
+msgstr[0] "стол"
+msgstr[1] "стола"
+msgstr[2] "столов"
 
-#: ../../examples/src/HookedComponent.js:10
+#: ../../examples/src/DecoratedClassComponent.js:10
 msgctxt "Context"
 msgid "Text with context"
 msgstr "Текст с контекстом"
+
+#: ../../examples/src/AliasUsingComponent.js:12
+#: ../../examples/src/TemplateUsingComponent.js:12
+msgctxt "Context"
+msgid "Text with context ${}"
+msgstr "Текст с контекстом ${}"

examples/src/AliasUsingComponent.js

@@ -0,0 +1,17 @@
+import React from 'react'
+import { useLocales } from 'react-localized'
+
+export default () => {
+  const { __, __p, __n, __np } = useLocales()
+  const name = 'Anna'
+  const i = 2
+  const j = 12
+  return (
+    <>
+      <p>{__`My name is ${name}`}</p>
+      <p>{__p('Context')`Text with context ${name}`}</p>
+      <p>{__n`${i} apple``${i} apples`(i)}</p>
+      <p>{__np('Context')`${j} table``${j} tables`(j)}</p>
+    </>
+  )
+}