@industry/gettext
v1.0.0
Published
Gettext translation helpers.
Downloads
6
Readme
WEKA Gettext
PHP with Laravel
The package aims to make translation using gettext painless and combines any app's translations with all weka/* and imverlag/* module translations.
Installation
$ composer require weka/gettext
This package utilizes Weka's PlatformService so there is no need for futher installation set up.
Configuration
Review the Laravel configuration file located in config/weka/gettext.php and provide paths to your *.po files.
Merge your app's translations
After you've provided your paths run $ php artisan gettext:merge.
Your translations are merged with all weka/* and imverlag/* translations. And you're able to immediately start using gettext. There is no futher configuration required.
Export to json
If your app contains custom translations you probably want them to be transformed to JSON and use the transformed JSON files with the JavaScript version of this package.
Make sure you've provided all the paths to your app's translations and run $ php artisan gettext:json.
The command will transform all your *.po files to JSON files containing all the translations, including plurals and plural settings, according to your *.po file. The JSON files will be located next to the *.po files.
You're able to use all the generated JSON files directly with the @industry/gettext npm package. Just head over to the JavaScript section of this readme to review futher JavaScript configuration requirements.
Usage
$message = _('This string will be translated.');
$message = gettext('This string will be translated.');The package provides the __ global helper function which you can use instead of _ and gettext.
// Equivalent to `gettext('This string will be translated.')` or `_('This string will be translated.')`
$message = __('This string will be translated.');Usage with sprintf
Support for php's sprintf is baked in.
All you need to do is just adding sprintf arguments using the package's global helper function __.
// The following equals to: sprintf(_('%d files deleted'), 12);
$messageWithSprintf = __('%d files deleted', 12); // Would translate "12 files deleted".
// The following equals to: sprintf(_('%d files deleted in directory %s.'), 7, '/foo/bar');
$messageWithPlaceholders = __('%d files deleted in directory %s.', 7, '/foo/bar'); // -> "7 files deleted in /foo/bar."Usage with Plurals
For plurals you can use the packages second global helper function _n instead of __ or _.
The signature of _n is: _n($singular, $plural, $amount).
Based on given amount and language settings the translation function automatically selects either the singular or plural version.
// Usage with plurals
$oneFile = _n('File deleted.', 'Files deleted.', 1); // In English this would result in "File deleted.".
$moreFiles = _n('File deleted', 'Files deleted', 12); // -> "Files deleted.".DO NOT build your own plural algorithm. The following code would result in broken translations for several languages! Don't do this!
$amount = 12;
$message = $amount > 1 ? __('Files deleted.') : __('File deleted.');Usage with Plurals and sprintf
To utilize sprintf all you need to do is adding your sprintf arguments to the global helper function _n.
Just as you would with the regular singular translations.
// ╔══> value for selecting either singular or plural version
_n('%d file deleted.', '%d files deleted.', 1, 1); // "1 File deleted."
// ╚══> sprintf argument
// ╔══> value for selecting either singular or plural version
_n('%d file deleted.', '%d files deleted.', 6, 6); // "6 Files deleted."
// ╚══> sprintf argument
// value for selecting singular or plural version <══╗
_n('%d file deleted in %s.', '%d files deleted in %s.', 12, 12, '/foo/bar'); // "12 Files deleted in /foo/bar."
// ╚═══╚══> sprintf argumentsJavaScript
Installation
$ yarn add --dev @industry/gettext
Relevant sections are highlighted with
// <<<<<<<
import webpack from 'webpack';
import path from 'path';
const TRANSLATIONS_DIR = path.resolve(__dirname, './translations'); // <<<<<<<
export const config = {
entry: {
'bundle': 'index.js'
},
output: {
path: 'dist/build',
filename: '[name].js'
},
module : {
rules : [
{
test: /\.js$/,
include: [
TRANSLATIONS_DIR, // <<<<<<<
],
use: {
loader: 'babel-loader',
}
},
]
},
resolve: {
extensions: ['.js'],
alias: {
['~translations']: TRANSLATIONS_DIR, // <<<<<<<
}
},
};
export default config;Configuration
Before using translation you'll need to provide proper translation files. When you're using WEKA module extractor and spreader all required files are auto generated and stored in the module's translation directory.
All you need to do is to pass the translations to gettext translator and specify which locale should be used.
Preferably the locale is coming directly from your server backend. For the sake if this guide we'll just use en here.
translations.js
import Translator from '@industry/gettext';
import dictionaries from '~translations/dictionaries.js';
const translator = new Translator()
.withLocale('en') // <<<<< Specify which locale should be used. Preferably this setting comes from the server.
.withDictionaries(dictionaries);
const gettext = translator.gettext;
const ngettext = translator.ngettext;
const format = translator.format;
export default gettext;
export { gettext as _, ngettext as _n, format, translator };Using browser's locale
You're able to set the locale to the browser's current locale. But you should select the locale always manually.
const translator = new Translator()
.withLocaleFromBrowser(window)
.withDictionaries(dictionaries);That's it -- translations are ready now. Head to next section for usage details.
Usage
import _ from './translations';
const message = _('This string will be translated.');Usage with sprintf
Support for sprintf-js is baked in. All you need to do is just adding sprintf arguments to the gettext function.
import _ from './translations';
const messageWithSprintf = _('%d files deleted', 12); // Would translate "12 files deleted".
const messageWithPlaceholders = _('%d files deleted in directory %s.', 7, '/foo/bar'); // -> "7 files deleted in /foo/bar."Usage with Plurals
For plurals use _n instead of _. The signature of _n is: _n(singular, plural, amount).
Based on given amount and language settings the translation function automatically selects either the singular or plural version.
import _n from './translations';
// Usage with plurals
const oneFile = _n('File deleted.', 'Files deleted.', 1); // In English this would result in "File deleted.".
const moreFiles = _n('File deleted', 'Files deleted', 12); // -> "Files deleted.".DO NOT build your own plural algorithm. The following code would result in broken translations for several languages! Don't do this!
import _ from './translations';
const amount = 12;
const message = amount > 1 ? _('Files deleted.') : _('File deleted.');Usage with Plurals and sprintf
To utilize sprintf all you need to do is adding your sprintf arguments to the gettext function. Just as you would with the regular singular translations.
import _n from './translations';
// ╔══> value for selecting either singular or plural version
_n('%d file deleted.', '%d files deleted.', 1, 1); // "1 File deleted."
// ╚══> sprintf argument
// ╔══> value for selecting either singular or plural version
_n('%d file deleted.', '%d files deleted.', 6, 6); // "6 Files deleted."
// ╚══> sprintf argument
// value for selecting singular or plural version <══╗
_n('%d file deleted in %s.', '%d files deleted in %s.', 12, 12, '/foo/bar'); // "12 Files deleted in /foo/bar."
// ╚═══╚══> sprintf arguments