Download the PHP package syriable/laravel-translations without Composer

Laravel Translations

Manage your Laravel translations from code — import and export language files, machine-translate with AI, enforce quality, track revision history, detect hardcoded strings, manage a glossary, report analytics, and expose KPIs through pre-built laravel-metrics definitions. It's a backend-only toolkit: one config file, one service provider, one Translations facade. No UI, no frontend, no opinions about how you render anything.

Table of contents

• Installation
• Configuration
• How it's modelled
• Usage
  • Reading and writing translations
  • Locales
  • Importing and exporting language files
  • AI translation
  • Quality checks
  • Validation rules
  • Glossary
  • Revision history
  • Review workflow
  • Comments
  • Analytics
  • Metrics
  • Scanning your source code
  • Activity log
  • Background jobs
• API reference
• Artisan commands
• Configuration reference
• Events
• Models
• Enums
• Contracts
• Testing
• Security
• Contributing
• Changelog
• License

Installation

Require the package via Composer:

Run the installer — it publishes the config file, runs the migrations, and (with --import) loads your existing language files:

Or do the steps yourself:

Requirements: PHP 8.4+, Laravel 12 or 13.

Dependencies: The package pulls in laravel/ai (AI translation and review) and syriable/laravel-metrics (pre-built KPI definitions). AI calls are still opt-in via config — set ai.enabled = true and configure a provider key in your .env before calling Translations::translate() or Translations::aiReview().

Configuration

Everything is driven by config/translations.php. The two settings you'll touch first:

All tables are prefixed (default tx_) and can live on a dedicated connection, so the package never clashes with your schema:

See the configuration reference for every key.

How it's modelled

Four core records describe your catalog:

A dotted key like auth.failed resolves to bundle auth + phrase failed. Nested lang files use their slash path as the bundle name (filament/resources/bundle-resource.title), matching Laravel's own group convention. Keys with no dot live in the JSON bundle (_json).

Every message carries a status (open → draft/pending_review → approved). Writing a value fires a MessageSaved event that records a revision, runs quality checks, and flushes analytics.

Usage

Everything is reachable from the Translations facade, or by resolving the underlying classes from the container (app(TranslationManager::class), app(Inspector::class), …). The examples use the facade.

Reading and writing translations

set() is wrapped in a database transaction and returns the saved Message.

Finding similar keys

Surface phrases in the same bundle that share a leading key segment — handy for spotting related rules while you work (e.g. validation.accepted and its accepted_if / accepted_unless cousins). Segments are split on ., _ and -.

It returns a Collection<Phrase> from the same bundle only, ordered by key, excluding the given phrase by default. An unknown key yields an empty collection.

Locales

Each Locale exposes computed accessors — flag (SVG data URI via outhebox/blade-flags) and translation_progress (percent of non-open messages) — and scopes enabled(), targets(), and withTranslationProgressCounts().

Importing and exporting language files

Import reads PHP (including nested directories), JSON and vendor namespace files from lang_path into the database. The whole import runs in a transaction and suppresses per-row events, so a large or --fresh import never bloats history or leaves a half-written catalog behind.

Export writes the database back to disk, preserving nesting, key sorting, plurals and Unicode:

Set export.approved_only in config to export only reviewer-approved strings.

Imports are the catalog's source of truth and skip per-row quality/revisions; run php artisan translations:validate afterwards to check imported strings.

AI translation

Requires laravel/ai and ai.enabled = true. Translations are produced through a swappable Translator contract, so the engine can be faked in tests with no HTTP.

Prompts are context-aware (glossary terms, developer notes, where the key is used, sibling keys) and fence untrusted context so it can't act as instructions. Context is on by default; pass 'context' => false (or set ai.context to false) for a leaner, cheaper prompt — useful on large batch runs. Every call is logged to tx_ai_usages with an estimated cost from ai.cost_rates.

To discover which providers are actually usable — allowlisted and configured with a key in .env (via the laravel/ai config) — call AiProviders::usable(). It returns a Collection<AiProvider> (Ollama is treated as usable without a key, since it authenticates via its URL):

Each suggestion in the returned TranslationResult carries a value (the translation as proposed), a base_value (the clean, copy/store-ready translation — the exact string to write to a language file, stripped of any framing the model may add such as Translate to German, for example: "…"), a confidence score, a recommended flag (exactly one variant is always recommended), and an optional note — a concise, human-readable explanation of why that wording was chosen (terminology, common usage, natural phrasing, framework conventions), written in the source language so the translator reading it understands the reasoning. Read the recommended variant directly:

base_value comes from a dedicated structured-output field the model fills, and is cleaned defensively (surrounding quotes stripped, and the quoted translation lifted out of an e.g. "…" example) so a "copy" button always gets just the translation. apply() stores best(), so the value written to your catalog is the clean one even when the model wraps its answer in commentary.

Swapping the engine (e.g. in tests) is a one-liner — Translator has a single method:

Quality checks

Ten pluggable checks compare each translation against its source. They run automatically on every save (when quality.run_on_save is on) and on demand.

Disable a check by removing its class from quality.checks, or add your own implementing Syriable\Translations\Contracts\QualityCheck.

AI quality review

The deterministic checks above catch mechanical problems (placeholders, HTML, plural selectors). For the linguistic ones they can't see — unnatural phrasing, gender issues, pluralization errors, context mismatches and cross-key inconsistencies — the package ships an AI reviewer. Like AI translation it requires laravel/ai and ai.enabled = true, and runs through a swappable Reviewer contract so it can be faked in tests with no HTTP.

It gathers the source/target pairs for the locale's translated messages, sends them to the model in batches (ai.review.batch_size, default 50) and returns a ReviewResult:

Each ReviewIssue carries the dotted key it refers to, a severity as a dedicated ReviewSeverity (Low, Medium, High — the reviewer's own priority scale, distinct from the deterministic checks' Severity), a description of the problem (in the source language), an optional suggestion explaining the fix, and — when the reviewer proposes a corrected translation — a baseSuggestion: that correction on its own, in the target language, cleaned of any framing so it can be copied straight into the catalog (same treatment as a translation suggestion's base_value). The reviewer fences untrusted source/target text so it can't act as instructions, drops any issue the model invents for a key that wasn't reviewed, and logs every batch to tx_ai_usages with an estimated cost. Unlike the deterministic checks it does not persist QualityIssue rows — it's an on-demand review you run before approving a batch.

Run it from the CLI (exits non-zero when high-priority issues are found, so it slots into CI):

Swapping the engine (e.g. in tests) is a one-liner — Reviewer has a single method:

Validation rules

For validating a translation value as it's submitted (e.g. in a form request or Livewire component), the package ships two reusable Laravel ValidationRules under Syriable\Translations\Rules. Each takes the Phrase the value belongs to, so it can compare against the source and the phrase's metadata:

• TranslationPlaceholdersRule — fails when the value drops a placeholder the phrase defines. Skips empty values and phrases with no placeholders. Its detection logic is reusable directly: TranslationPlaceholdersRule::missingPlaceholders($phrase, $value) returns the missing placeholders.
• TranslationPluralRule — for plural phrases, requires the value to match the source: when the source uses explicit selectors ({0}, [1,19], [20,*]) every selector must be preserved exactly, otherwise the pipe-separated variant count must match. Skips empty values and non-plural phrases.

These complement the quality checks: the rules block bad input up front, while the checks audit already-stored translations.

Glossary

Per-locale approved terminology that feeds both AI prompts and the glossary quality check.

Revision history

Every value change is recorded in tx_revisions. Roll a message back, or undo a batch of changes.

Prune old history with php artisan translations:prune-revisions (keeps the latest per message).

Who made the change

Revision::member(), Message::translator() and Message::reviewer() are belongsTo relations against your configured member_model — resolving $revision->member/$message->translator needs no manual lookup:

You don't need to pass by explicitly for this to work. Every write path (set(), AI translation, review approve/reject, rollback) accepts an optional by in its $options/args, but when it's omitted the package asks Syriable\Translations\Contracts\ResolvesActor to identify the actor instead. The default implementation reads the currently authenticated user off auth_guard (null = your app's default guard) — so changed_by / translated_by / reviewed_by are filled in automatically, including who triggered an AI translation (the human who clicked "translate", not the AI itself — that's already tracked separately via reason: RevisionReason::Ai and Message::ai_provider). When nobody is authenticated (a console command, queue job, or script), the resolver falls back to system_actor (null by default, so unattended runs stay honestly unattributed rather than impersonating a user). Bind your own ResolvesActor in the container to customize resolution — e.g. to tag queue jobs with a service-account id:

Review workflow

When review.enabled is on, non-reviewer saves land in pending_review instead of approved.

The actor string is advisory — it's recorded, not enforced. Authorization is your application's job. MemberRole is a plain value object; if your member_model implements Syriable\Translations\Contracts\HasTranslationRole, the package ships a MessagePolicy stub you can register yourself (Gate::policy(Message::class, MessagePolicy::class)), or write your own. See Security.

Comments

Attach threaded discussion to a message. Comments fire CommentPosted, which the package listens to for activity logging when activities.enabled is on:

Each Comment belongs to its message and optionally to a member (via member_model).

Analytics

The Insights service returns simple, cached PHP arrays — handy for dashboards that don't need ranges or comparisons:

Metrics

For richer analytics — date ranges, trend buckets, partition breakdowns, formula datasets, and a normalized API payload — the package registers four metrics with syriable/laravel-metrics at boot. Run them by key:

Only enabled, non-source target locales are included. Quality weights default to 60% review (approved / translated) and 40% validation (100 - issues / translated * 100); override via translations.analytics.quality.weights.

Metric classes live in Syriable\Translations\Metrics if you want to inspect or extend them. See the laravel-metrics README for ranges, comparisons, caching, and building your own metrics.

Scanning your source code

Both return a stats array. Run them in the background with the --queue flag on the corresponding commands, or set scanning.scan_after_import to queue a usage scan after every import.

Hardcoded-string hits are stored as LooseString records (Pending → Resolved when the source text disappears, or Converted / Ignored when you action them). Persisted ignore rules live in IgnoredString.

Activity log

When activities.enabled is on, the package automatically records status changes and comments via RecordStatusActivity and RecordCommentActivity. For arbitrary actions, use the recorder directly:

Background jobs

Long-running work can be queued on the connection/name from translations.queue:

ScanUsageAfterImport also queues a usage scan when scanning.scan_after_import is enabled.

API reference

Every method on the Translations facade (backed by TranslationManager):

The sub-services:

Artisan commands

Configuration reference

Events

Hook into the translation lifecycle with standard Laravel listeners:

Internally, MessageSaved drives RecordRevision, RunQualityChecks and FlushInsightsCache; MessageStatusChanged and CommentPosted drive activity logging (when enabled); ImportFinished drives ScanUsageAfterImport (when enabled) and a cache flush.

Models

All models live in Syriable\Translations\Models and use the configured table prefix.

Enums

In Syriable\Translations\Enums:

• MessageStatus — Open, Draft, PendingReview, Approved. Methods: label(), isTranslated().
• MemberRole — Owner, Admin, Reviewer, Translator, Viewer. Methods: level(), isAtLeast(), canTranslate(), canReview(), canManage(). Not tied to any model; resolve it for your member_model by implementing Contracts\HasTranslationRole.
• RevisionReason — Manual, Import, Ai, Rollback, Bulk, QualityFix. Method: label().
• Severity — Error, Warning, Info (deterministic quality checks). Method: order().
• ReviewSeverity — Low, Medium, High (AI quality-review priority). Methods: order(), fromModel().
• LooseStringStatus — Pending, Converted, Ignored, Resolved.
• AiProvider — OpenAI, Anthropic, Gemini, Groq, Mistral, XAI, DeepSeek, OpenRouter, Ollama, Cohere. Used for allowlisting and UI labels/icons (via filament/support contracts).
• Direction — Ltr, Rtl. Auto-detected for known locale codes; overridable on addLocale().
• Tone — Neutral, Formal, Informal, Friendly, Technical. Default per locale; passed to AI prompts.
• Priority — Critical, High, Medium, Low, Optional. Stored on each Phrase (default Optional).

Contracts

Swappable interfaces in Syriable\Translations\Contracts:

Testing

The suite runs on Pest 4 + Orchestra Testbench against in-memory SQLite. AI paths are tested through the Translator contract with FakeTranslator, so no test makes a network call.

Security

This is a backend-only toolkit with no auth layer; a few responsibilities sit with the consuming application (importing .php lang files executes them, models are mass-assignable, AI output is untrusted, authorization is yours). Read SECURITY.md for the full trust model and how to report a vulnerability.

Contributing

See CONTRIBUTING.md. Run composer test, composer analyse, and composer format before opening a PR.

Changelog

See CHANGELOG.md.

License

The MIT License (MIT). See LICENSE.md.