Localization
The framework supports WordPress localization files (POT, PO, and MO files).
By default, localization files should be stored in the folder [path to project]/assets/lang.
Ayuco Command
Before using any of the commands below, make sure to enable localize at your project configuration (see here).
Generate POT file command
The generate POT command is used to scan your code and generate a .pot file.
The .pot file is your master file with all translations which will be used to generate PO and MO files; this file only contains the original text definitions, and it doesn't contain the translations.
php ayuco generate pot {language}
| {language} | OPTIONAL The language code of the text scanned from the code. By default, it is set as en. |
How is the code scanned?
The command will look through the code for valid WordPress internationalization functions that have been defined under the text-domain of the project. If a function is detected but is not under the text-domain of the project, then it will not be added as a valid translation.These are the supported WordPress internationalization functions.
The command will generate the file [path to project]/assets/lang/[text-domain].pot.
Generate PO file command
The generate PO command is used to generate a .po file from an existing .pot file. By default, the command creates and/or updates the .pot file. If the .po file already exists, then the command will append to it all missing translations detected in the POT file and will respect existing translated ones.
php ayuco generate po:{locale} {language}
| {locale} | The WordPress locale code to generate (i.e. en_US). List of locale codes |
| {language} | OPTIONAL The language code of the text scanned from the code. By default, it is set as en. |
The command will generate the file [path to project]/assets/lang/[text-domain]-[locale].po.
By using the --clear argument, the command supports clearing the .po file and creating it from scratch, wiping out all existing translated translations. For example:
php ayuco generate po:en_US --clear
Generate MO file command
The generate MO command is used to generate a .mo file from an existing .po file.
php ayuco generate mo:{locale}
| {locale} | The WordPress locale code to generate (i.e. en_US). |
The command will generate the file [path to project]/assets/lang/[text-domain]-[locale].mo.
Generate translations command
The generate translations command will create or update the indicated .po file and will read all its translations, prompting in the console a Wizard-like experience that allows translating every text found.
The command generates a .mo file once all text strings have been translated.
php ayuco generate translations:{locale}
| {locale} | The WordPress locale code to generate (i.e. en_US). |
Text Domain
Localization in WordPress works by text domains. These domains are attached to each custom text string found inside the code of a plugin or theme and help WordPress who will translate them.
WordPress expects the domain owner to provide it with PO language files that will be used for translations.
Recommendation
Define your text-domain based on your namespace. WordPress.org will assign you a text-domain (slug) if you plan to publish the project on their website.Ayuco Command
Ayuco asks for a text-domain during the setup command.
Alternatively, the text domain can be changed by using the set command:
php ayuco set domain:{text-domain}
Configuration
Localization settings can be modified in the configuration file (located at app/Config/app.php).
return [
// Other settings ...
'localize' => [
// Enables or disables localization
'enabled' => false,
// Default path for language files
'path' => __DIR__ . '/../../assets/lang/',
// Text domain
'textdomain' => 'my-app',
// Unload loaded locale files before localization
'unload' => false,
// Flag that indicates if this is a WordPress.org plugin/theme
'is_public' => false,
],
// Other settings ...
];