woocommerce/plugins/woocommerce-blocks/docs/internal-developers/translations/translations-in-JS-TS-files.md

101 lines
2.8 KiB
Markdown
Raw Normal View History

Add docs about translation handling (https://github.com/woocommerce/woocommerce-blocks/pull/6405) * Create translation handling files * Add docs about “Translation basics” * Update docs for “Translation basics” * Add docs about “Translations in PHP files” * Add docs about “Translations in JS/TS files” * Update docs for “Translation basics” * Add docs for “Translation management” * Add docs for “Translations in FSE templates” * Add “Translations” to “WooCommerce Blocks Handbook” * Add docs for “Lazy-load translations” * Rewrite first paragraph of “Translations in FSE templates” * Fix typo * Update repo URL * Remove obsolete space and comma * Update repo URL * Rename lazy-load file * Add section about “sprintf()” to “Translations in JS/TS files” * Remove reference to “npm install @wordpress/i18n” * Add docs for “Translation files and loading” * Rename readme.md to README.md * Remove double file extension * Remove self-explaining explenations * Update docs/README.md Co-authored-by: Thomas Roberts <5656702+opr@users.noreply.github.com> * Update docs/translations/translation-basics.md Co-authored-by: Thomas Roberts <5656702+opr@users.noreply.github.com> * Update docs/translations/translation-basics.md Co-authored-by: Thomas Roberts <5656702+opr@users.noreply.github.com> * Update docs/translations/translation-loading.md Co-authored-by: Thomas Roberts <5656702+opr@users.noreply.github.com> * Update docs/translations/translation-loading.md Co-authored-by: Thomas Roberts <5656702+opr@users.noreply.github.com> * Update docs/translations/translation-loading.md Co-authored-by: Thomas Roberts <5656702+opr@users.noreply.github.com> * Update docs/translations/translation-loading.md Co-authored-by: Thomas Roberts <5656702+opr@users.noreply.github.com> * Update docs/translations/translation-loading.md Co-authored-by: Thomas Roberts <5656702+opr@users.noreply.github.com> * Update docs/translations/translation-loading.md Co-authored-by: Thomas Roberts <5656702+opr@users.noreply.github.com> * Update docs/translations/translation-management.md Co-authored-by: Thomas Roberts <5656702+opr@users.noreply.github.com> * Update docs/translations/translations-in-FSE-templates.md Co-authored-by: Thomas Roberts <5656702+opr@users.noreply.github.com> * Clarify how to use variables in translations * Change “i18n” to “internationalization (i18n)” * Link translation functions to the WordPress reference * Add Translation management to Translation management * Update “Translations in FSE templates” * Lint Markdown files * Update chunk translation register functions * Update function that loads the translation file * Update information about lazy-loading * Adjust lazy-loading docs title and file name Co-authored-by: Thomas Roberts <5656702+opr@users.noreply.github.com>
2022-06-10 15:40:05 +00:00
# Translations in JS/TS files
In comparison to PHP files, translations in JS/TS files require a few additional steps. To use translation functions in JS/TS, the dependency `@wordpress/i18n` needs to be included at the top of the corresponding file:
```ts
import { sprintf, _n } from '@wordpress/i18n';
```
Once that dependency had been included, the translation function can than be used.
## Usage of localization functions
### `__()`
The function `__()` retrieves the translation of `$text`.
```ts
// Schema
const translation = __( string text, string domain = 'default' );
// Example
import { __ } from '@wordpress/i18n';
const translation = __( 'Place Order', 'woo-gutenberg-products-block' );
```
See also <https://developer.wordpress.org/reference/functions/__/>.
### `_n()`
The function `_n()` translates and retrieves the singular or plural form based on the supplied number.
```ts
// Schema
const translation = _n( string single, string plural, int number, string domain = 'default' );
// Example
import { sprintf, _n } from '@wordpress/i18n';
const translation = sprintf(
/* translators: %s number of products in cart. */
_n(
'%d product',
'%d products',
Math.abs( category->count ),
'woo-gutenberg-products-block'
),
Math.abs( category->count )
);
```
See also <https://developer.wordpress.org/reference/functions/_n/>.
### `_x()`
The function `_x()` retrieves a translated string with gettext context.
```ts
// Schema
const translation = _x( string text, string context, string domain = 'default' );
// Example
import { _x } from '@wordpress/i18n';
const translation = _x( 'Draft', 'Order status', 'woo-gutenberg-products-block' );
```
See also <https://developer.wordpress.org/reference/functions/_x/>.
### `_nx()`
The function `_nx()` translates and retrieves the singular or plural form based on the supplied number, with gettext context.
```ts
// Schema
const translation = _nx( string single, string plural, int number, string context, string domain = 'default' );
// Example
import { sprintf, _nx } from '@wordpress/i18n';
const translation = sprintf(
/* translators: %s number of products in cart. */
_nx(
'%d product',
'%d products',
Math.abs( category->count ),
'Number of products in the cart',
'woo-gutenberg-products-block'
),
Math.abs( category->count )
);
```
See also <https://developer.wordpress.org/reference/functions/_nx/>.
### Template literals and variables
Template literals cannot be used in JS/TS translations. To use variables in JS/TS translations, the function `sprintf()` needs to be used, as variables cannot be used directly. Various examples on how to use this function, can be seen in the previous examples.
See also <https://developer.wordpress.org/block-editor/reference-guides/packages/packages-i18n/#sprintf>.