Usage

Creating a Translator

The Translator class requires a ContextInterface instance that provides the plugin's text domain.

use WPZylos\Framework\I18n\Translator;

$translator = new Translator($context);

When using the service provider, the translator is registered as a singleton and can be resolved from the container:

$translator = $app->make(Translator::class);
$translator = $app->make('translator');

Basic Translation

translate()

Returns the translated string using the plugin's text domain.

$label = $translator->translate('Settings');
$title = $translator->translate('My Plugin Name');

echo()

Translates a string, escapes it with esc_html(), and echoes it directly. Use in templates and views.

// In a template
<h1><?php $translator->echo('Page Title'); ?></h1>
<button><?php $translator->echo('Save Changes'); ?></button>

Formatted Strings

sprintf()

Translates a string and then applies sprintf() formatting.

$greeting = $translator->sprintf('Hello, %s!', $userName);
$status = $translator->sprintf('Processing %d of %d items', $current, $total);

Pluralization

plural()

Returns the correct singular or plural form based on the count.

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

// Use with sprintf for the number
$output = sprintf($message, $count);

Contextual Translation

translateWithContext()

Provides disambiguation context for translators when the same English word has different meanings.

// "Post" as a noun (blog post)
$noun = $translator->translateWithContext('Post', 'noun');

// "Post" as a verb (to post/submit)
$verb = $translator->translateWithContext('Post', 'verb');

// "Order" in different contexts
$shopOrder = $translator->translateWithContext('Order', 'e-commerce');
$sortOrder = $translator->translateWithContext('Order', 'sorting');

Escaped Output

esc()

Returns the translated string escaped for safe HTML output. Uses esc_html__() internally.

$safe = $translator->esc('Settings');
// Safe to use in HTML: <span><?php echo $safe; ?></span>

escAttr()

Returns the translated string escaped for use in HTML attributes. Uses esc_attr__() internally.

$attr = $translator->escAttr('Click to save');
// Safe for attributes: <button title="<?php echo $attr; ?>">

Text Domain

textDomain()

Returns the plugin's text domain string.

$domain = $translator->textDomain(); // e.g. 'my-plugin'

I18n Class (Translation Loading)

The I18n class handles loading translation files (.mo files) for the plugin.

Creating an I18n Instance

use WPZylos\Framework\I18n\I18n;

$i18n = new I18n($context);

load()

Loads translations by calling load_plugin_textdomain(). Translation files are expected in resources/lang/ within the plugin directory.

$success = $i18n->load(); // Returns true if loaded

Expected file structure:

my-plugin/
  resources/
    lang/
      my-plugin-de_DE.mo
      my-plugin-fr_FR.mo
      my-plugin-es_ES.mo

loadFor() (Static)

Static convenience method that creates an instance and loads translations in one call.

I18n::loadFor($context);

isLoaded()

Check if translations have already been loaded.

if (! $i18n->isLoaded()) {
    $i18n->load();
}

getMoFilePath()

Get the full path to a .mo file for a specific locale.

$path = $i18n->getMoFilePath('de_DE');
// -> /path/to/plugin/resources/lang/my-plugin-de_DE.mo

I18nServiceProvider

The I18nServiceProvider handles automatic registration and translation loading.

register()

During registration, it:

1. Registers Translator::class as a singleton (using $app->context())
2. Binds a 'translator' alias
3. Registers I18n::class as a singleton

// After registration:
$translator = $app->make(Translator::class);
$translator = $app->make('translator');
$i18n = $app->make(I18n::class);

boot()

During boot, it hooks into WordPress init action to load translations automatically:

// Internally adds:
add_action('init', function () {
    $i18n = $this->make(I18n::class);
    $i18n->load();
});

No manual loading is needed when using the service provider.