Registration & sync

composer require langsys/langsys-php

PHP 7.4+

Automatic registration (queuing)

The SDK queues new phrases and content blocks during translation and flushes them at the end of the request:

$client->translate('New phrase');
$client->translateContentBlock('<p>New content</p>');
$client->translatePage($html);

$result = $client->flushPendingRegistrations();
// ['phrases' => 5, 'content_blocks' => 2, 'success' => true]

$client->hasPendingRegistrations();
$client->getPendingPhrases();
$client->getPendingContentBlocks();
$client->clearPendingRegistrations();

With a read-only API key, items are queued but silently skipped during flush (no errors).

Registering phrases

Requires a write-type API key.

$client->registerPhrases(['New Feature', 'Click Here', 'Learn More']);

$client->registerPhrases([
    ['phrase' => 'Dashboard', 'category' => 'Navigation'],
    ['phrase' => 'Submit', 'category' => 'Forms'],
]);

$client->registerPhrases([
    ['phrase' => 'Copyright 2024', 'category' => 'Footer', 'translatable' => false],
]);

Register content blocks

Phrases are automatically extracted from the HTML:

$client->registerContentBlock('<nav><a>Home</a><a>About</a></nav>');
$client->registerContentBlock($html, 'Navigation');
$client->registerContentBlock($html, 'Navigation', 'Main Navigation Menu');
$client->registerContentBlock($html, 'Navigation', 'Main Navigation Menu', 'main-menu-001');

Auto-extraction supports text nodes, button and submit input values, and select option text. Use translate="no" to exclude elements.

Relative URLs in src, srcset, and poster are converted to absolute URLs using base_url, LANGSYS_BASE_URL, or auto-detected HTTP_HOST.

Default translatable attributes: placeholder, alt, title, label; ARIA (aria-label, aria-placeholder, …); validation (data-error, data-error-message, …); and common framework tooltip/confirm attributes.

$client->addTranslatableAttributes(['data-label', 'data-tooltip']);
$client->setTranslatableAttributes(['data-label', 'data-text']);
$client->resetTranslatableAttributes();
$client->getTranslatableAttributes();

Bulk registration

$resource = $client->translatableItems();

$resource->createPhrasesWithCategory(['Error 404', 'Error 500'], 'Errors');

$resource->createFromMap([
    'Navigation' => ['Home', 'About', 'Contact'],
    'Forms' => ['Submit', 'Cancel', 'Reset'],
]);

Syncing phrases

sync() compares local phrases against the remote API and registers any new ones:

$result = $client->sync([
    ['phrase' => 'Home', 'category' => 'UI'],
    ['phrase' => 'New Feature', 'category' => 'UI'],
], 'es-es');

// translations, new_phrases, synced

If using a read-only API key, sync() identifies new phrases but won’t register them (synced will be false).

Feedback