Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/erikyo/i18n
https://github.com/erikyo/i18n
Last synced: about 2 months ago
JSON representation
- Host: GitHub
- URL: https://github.com/erikyo/i18n
- Owner: erikyo
- Created: 2024-05-06T11:22:08.000Z (8 months ago)
- Default Branch: master
- Last Pushed: 2024-05-10T17:28:29.000Z (8 months ago)
- Last Synced: 2024-10-10T00:42:43.821Z (3 months ago)
- Language: TypeScript
- Size: 123 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
Awesome Lists containing this project
README
### !!! Fork of the @wordpress/I18n package !!!
If are looking for the original package this is the link https://github.com/WordPress/gutenberg/blob/trunk/packages/i18n/
## Key Differences with the original package
- This repo has been completely rewritten in ts, the code is much more readable and uses modern javascript (i.e. classes)
- The tests are those of the original repository, plus others I added
- I fixed a script to convert pot to php that was in the original repository (but not documented afaik), and added my own cli script to generate pot files similar to wp-cli make-pot
- I have changed a large part of the dependencies. for example we now use @tannin/sprintf and not sprintfjs or, for dev dependencies biome instead of prettier and eslint or vitest instead of jest, this greatly reduces the space occupied and the time to install the package
- Slightly faster compared to the original repo
# Internationalization (i18n)
Internationalization utilities for client-side localization. See [How to Internationalize Your Plugin](https://developer.wordpress.org/plugins/internationalization/how-to-internationalize-your-plugin/) for server-side documentation.
## Installation
Install the module:
```bash
npm install @wp-blocks/i18n --save
```
_This package assumes that your code will run in an **ES2015+** environment. If you're using an environment that has limited or no support for such language features and APIs, you should include [the polyfill shipped in `@wordpress/babel-preset-default`](https://github.com/WordPress/gutenberg/tree/HEAD/packages/babel-preset-default#polyfill) in your code._
## CLI scripts
- `npx pot-to-php`: (included in the original I18n package) Converts the pot files into php files
- `npx make-pot`: 🆕 Makepot is a script similar to the original included with wp-cli, emits the pot file for themes and plugins and supports typescript, jsx, tsx. More info here https://www.npmjs.com/package/@wp-blocks/make-pot
## Usage
```js
import { sprintf, _n } from '@wordpress/i18n';
sprintf( _n( '%d hat', '%d hats', 4, 'text-domain' ), 4 );
// 4 hats
```
For a complete example, see the [Internationalization section of the Block Editor Handbook](https://developer.wordpress.org/block-editor/developers/internationalization/).
## API
### createI18n
Create an i18n instance
_Parameters_
- _initialData_ `[LocaleData]`: Locale data configuration.
- _initialDomain_ `[string]`: Domain for which configuration applies.
- _hooks_ `[Hooks]`: Hooks implementation.
_Returns_
- `I18n`: I18n instance.
### defaultI18n
Default, singleton instance of `I18n`.
### getLocaleData
Returns locale data by domain in a Jed-formatted JSON object shape.
_Related_
-
_Parameters_
- _domain_ `[string]`: Domain for which to get the data.
_Returns_
- `LocaleData`: Locale data.
### hasTranslation
Check if there is a translation for a given string (in singular form).
_Parameters_
- _single_ `string`: Singular form of the string to look up.
- _context_ `[string]`: Context information for the translators.
- _domain_ `[string]`: Domain to retrieve the translated text.
_Returns_
- `boolean`: Whether the translation exists or not.
### isRTL
Check if current locale is RTL.
**RTL (Right To Left)** is a locale property indicating that text is written from right to left. For example, the `he` locale (for Hebrew) specifies right-to-left. Arabic (ar) is another common language written RTL. The opposite of RTL, LTR (Left To Right) is used in other languages, including English (`en`, `en-US`, `en-GB`, etc.), Spanish (`es`), and French (`fr`).
_Returns_
- `boolean`: Whether locale is RTL.
### resetLocaleData
Resets all current Tannin instance locale data and sets the specified locale data for the domain. Accepts data in a Jed-formatted JSON object shape.
_Related_
-
_Parameters_
- _data_ `[LocaleData]`: Locale data configuration.
- _domain_ `[string]`: Domain for which configuration applies.
### setLocaleData
Merges locale data into the Tannin instance by domain. Accepts data in a Jed-formatted JSON object shape.
_Related_
-
_Parameters_
- _data_ `[LocaleData]`: Locale data configuration.
- _domain_ `[string]`: Domain for which configuration applies.
### sprintf
Returns a formatted string. If an error occurs in applying the format, the original format string is returned.
_Related_
-
_Parameters_
- _format_ `string`: The format of the string to generate.
- _args_ `...*`: Arguments to apply to the format.
_Returns_
- `string`: The formatted string.
### subscribe
Subscribes to changes of locale data
_Parameters_
- _callback_ `SubscribeCallback`: Subscription callback
_Returns_
- `UnsubscribeCallback`: Unsubscribe callback
### \_n
Translates and retrieves the singular or plural form based on the supplied number.
_Related_
-
_Parameters_
- _single_ `string`: The text to be used if the number is singular.
- _plural_ `string`: The text to be used if the number is plural.
- _number_ `number`: The number to compare against to use either the singular or plural form.
- _domain_ `[string]`: Domain to retrieve the translated text.
_Returns_
- `string`: The translated singular or plural form.
### \_nx
Translates and retrieves the singular or plural form based on the supplied number, with gettext context.
_Related_
-
_Parameters_
- _single_ `string`: The text to be used if the number is singular.
- _plural_ `string`: The text to be used if the number is plural.
- _number_ `number`: The number to compare against to use either the singular or plural form.
- _context_ `string`: Context information for the translators.
- _domain_ `[string]`: Domain to retrieve the translated text.
_Returns_
- `string`: The translated singular or plural form.
### \_x
Retrieve translated string with gettext context.
_Related_
-
_Parameters_
- _text_ `string`: Text to translate.
- _context_ `string`: Context information for the translators.
- _domain_ `[string]`: Domain to retrieve the translated text.
_Returns_
- `string`: Translated context string without pipe.
### \_\_
Retrieve the translation of text.
_Related_
-
_Parameters_
- _text_ `string`: Text to translate.
- _domain_ `[string]`: Domain to retrieve the translated text.
_Returns_
- `string`: Translated text.
## Credits
The original authors of this package
