API Reference

Translator

WPZylos\Framework\I18n\Translator

Translation wrapper that provides localized strings using the plugin's text domain. Always uses $context->textDomain() - never hardcoded.

__construct(ContextInterface $context)

Create a new translator.

$translator = new Translator($context);

translate(string $text): string

Translate a string. Wraps WordPress __() with the plugin's text domain.

Returns: string - Translated text.

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

echo(string $text): void

Translate a string, escape with esc_html(), and echo it directly.

$translator->echo('Save Changes');

sprintf(string $text, mixed ...$args): string

Translate a string and apply sprintf() formatting.

Returns: string - Translated and formatted text.

$msg = $translator->sprintf('Hello, %s!', $name);

plural(string $single, string $plural, int $number): string

Translate a plural string. Wraps WordPress _n() with the plugin's text domain.

Returns: string - Translated text.

$text = $translator->plural('One item', '%d items', $count);

translateWithContext(string $text, string $context): string

Translate a string with disambiguation context. Wraps WordPress _x() with the plugin's text domain.

Returns: string - Translated text.

$noun = $translator->translateWithContext('Post', 'noun');
$verb = $translator->translateWithContext('Post', 'verb');

textDomain(): string

Get the plugin's text domain.

Returns: string - The text domain.

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

esc(string $text): string

Translate and escape for safe HTML output. Wraps WordPress esc_html__().

Returns: string - Escaped translated text.

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

escAttr(string $text): string

Translate and escape for use in HTML attributes. Wraps WordPress esc_attr__().

Returns: string - Escaped translated text.

$attr = $translator->escAttr('Click here');

I18n

WPZylos\Framework\I18n\I18n

Handles loading translation files for a plugin.

__construct(ContextInterface $context)

Create a new i18n loader.

$i18n = new I18n($context);

load(): bool

Load translations. Calls load_plugin_textdomain() with the correct paths. Translation files are loaded from {plugin}/resources/lang/. Only loads once; subsequent calls return true immediately.

Returns: bool - true if loaded successfully.

$success = $i18n->load();

static loadFor(ContextInterface $context): bool

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

Returns: bool - true if loaded successfully.

I18n::loadFor($context);

isLoaded(): bool

Check if translations have been loaded.

Returns: bool

$i18n->isLoaded(); // true/false

getMoFilePath(string $locale): string

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

Returns: string - Full path to the .mo file.

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

I18nServiceProvider

WPZylos\Framework\I18n\I18nServiceProvider extends WPZylos\Framework\Core\ServiceProvider

Registers the translation system in the application container.

register(ApplicationInterface $app): void

Registers translation services:

1. Translator::class singleton (using $app->context())
2. 'translator' alias bound to the Translator singleton
3. I18n::class singleton (using $app->context())

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

boot(ApplicationInterface $app): void

Hooks into WordPress init action to automatically load translations.

Internally:

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