README

Internationalization wrapper for WPZylos framework.

📖 Full Documentation | 🐛 Report Issues

Features

Translation - Plugin-scoped translate(), echo(), sprintf() methods
Pluralization - Handle singular/plural forms with plural()
Context Support - Disambiguate translations with translateWithContext()
Escaped Output - Safe HTML/attribute output with esc() and escAttr()
Auto Loading - Automatic text domain loading via service provider
JavaScript Translations - Attach WordPress JSON translations to script handles
Vue and React Bridges - Use WordPress wp.i18n in Vue and React without custom key maps

Requirements

Requirement	Version
PHP	^8.0
WordPress	6.0+

Installation

composer require KYNetCode/wpzylos-i18n

Quick Start

use WPZylos\Framework\I18n\Translator;

$translator = new Translator($context);

// Translate strings
$label = $translator->translate('Hello World');

// Echo with HTML escaping
$translator->echo('Save Changes');

// Pluralization
$message = $translator->plural(
    'You have %d item',
    'You have %d items',
    $count
);

// Formatted translation
$greeting = $translator->sprintf('Hello, %s!', $userName);

Core Features

Translation Methods

// Simple translation
$label = $translator->translate('Settings');

// Echo (outputs esc_html-escaped translation)
$translator->echo('Save Changes');

// With sprintf formatting
$msg = $translator->sprintf('Welcome, %s!', $name);

// Pluralization
$text = $translator->plural(
    'You have %d item',
    'You have %d items',
    $count
);

// Contextual translation
$post = $translator->translateWithContext('Post', 'noun');

Escaped Output

// HTML-safe translation
$safe = $translator->esc('Settings');

// Attribute-safe translation
$attr = $translator->escAttr('Click here');

Text Domain

// Get the plugin's text domain
$domain = $translator->textDomain();

Translation Loading

use WPZylos\Framework\I18n\I18n;

// Instance usage
$i18n = new I18n($context);
$i18n->load();
$i18n->isLoaded(); // true

// Static convenience
I18n::loadFor($context);

// Get MO file path
$path = $i18n->getMoFilePath('de_DE');
// -> {plugin}/resources/lang/{domain}-de_DE.mo

JavaScript Translations

Use setScriptTranslations() after enqueueing a WordPress script handle. The package uses the plugin text domain from the WPZylos context and the default resources/lang directory.

use WPZylos\Framework\I18n\I18n;

$i18n = new I18n($context);

wp_enqueue_script(
    'my-plugin-admin',
    plugins_url('dist/admin.js', __FILE__),
    ['wp-i18n'],
    '1.0.0',
    true
);

$i18n->setScriptTranslations('my-plugin-admin');

For multiple handles:

$i18n->setScriptTranslationsFor([
    'my-plugin-admin',
    'my-plugin-frontend',
]);

WordPress expects JSON translation files in the standard script translation format generated by wp i18n make-json, usually inside resources/lang.

JavaScript API

The JavaScript bridge delegates to WordPress wp.i18n. If wp.i18n is not available yet, it safely returns the original string. The original English text is the gettext msgid; no extra key map is required.

import {__, _x, _n, sprintf, setDefaultTextDomain} from './vendor/kynetcode/wpzylos-i18n/resources/js/index.js';

setDefaultTextDomain('my-plugin');

__('Hello World');
_x('Post', 'noun');
_n('One item', '%d items', count);
sprintf(__('Hello, %s!'), userName);

Vue Usage

import {createApp} from 'vue';
import {createVueI18nPlugin} from './vendor/kynetcode/wpzylos-i18n/resources/js/vue.js';
import App from './App.vue';

createApp(App)
    .use(createVueI18nPlugin({textDomain: 'my-plugin'}))
    .mount('#app');

Then use the original strings directly in Vue templates:

<template>
    <button>{{ __('Save Changes') }}</button>
    <p>{{ sprintf(__('Hello, %s!'), customerName) }}</p>
</template>

Vue apps also receive $__, $_x, $_n, $_nx, $sprintf, and $isRTL aliases for projects that prefer Vue-style global property names.

Composition API usage:

import {useWpZylosI18n} from './vendor/kynetcode/wpzylos-i18n/resources/js/vue.js';

const {__} = useWpZylosI18n();

React Usage

import {I18nProvider, useI18n} from './vendor/kynetcode/wpzylos-i18n/resources/js/react.js';

function SaveButton() {
    const {__} = useI18n();

    return <button>{__('Save Changes')}</button>;
}

export default function App() {
    return (
        <I18nProvider textDomain="my-plugin">
            <SaveButton />
        </I18nProvider>
    );
}

Related Packages

Package	Description
wpzylos-core	Application foundation
wpzylos-scaffold	Plugin template

Documentation

For comprehensive documentation, tutorials, and API reference, visit wpzylos.com.

Support the Project

License

MIT License. See LICENSE for details.

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

Made with love by KYNetCode

kynetcode / wpzylos-i18n

Maintainers

Package info

Fund package maintenance!

Statistics

Security