Artisan Commands

Three commands cover everything: stringhive:push sends your source strings to Stringhive, stringhive:pull brings translated files back, and stringhive:audit diffs your local keys against Stringhive.

stringhive:push

Reads your lang directory and pushes source strings to Stringhive.

php artisan stringhive:push [<hive>]

The hive argument is optional when STRINGHIVE_HIVE is set in .env.

Options

Examples

# Push source strings
php artisan stringhive:push my-app

# Push source strings and seed all local translations too
php artisan stringhive:push my-app --with-translations

# Keep the hive in sync — removes strings deleted from your files
php artisan stringhive:push my-app --sync

# Wipe translations whenever a source string changes
php artisan stringhive:push my-app --conflict-strategy=clear

# Skip files you manage locally
php artisan stringhive:push my-app --exclude=auth.php --exclude=passwords.php

# Only push specific files
php artisan stringhive:push my-app --include=app.php --include=validation.php

The output tells you what happened:

Pushing to hive: my-app
  source — created: 12  updated: 3  unchanged: 1230  cleared: 0
Done.

stringhive:pull

Exports translated locales from Stringhive and writes them to your lang directory.

php artisan stringhive:pull [<hive>]

The source locale is skipped by default — you own that locally.

Options

Examples

# Pull all translated locales
php artisan stringhive:pull my-app

# Pull just Spanish
php artisan stringhive:pull my-app --locale=es

# Pull as JSON files
php artisan stringhive:pull my-app --format=json

# Pull everything, including the source locale
php artisan stringhive:pull my-app --include-source

# Preview before committing
php artisan stringhive:pull my-app --dry-run

Dry-run output:

[dry-run] No files will be written.
Pulling from hive: my-app
  [dry-run] Would write: /var/www/lang/es/app.php
  [dry-run] Would write: /var/www/lang/es/auth.php
Done.

stringhive:audit

Diffs your codebase against Stringhive to surface missing and orphaned keys, and optionally checks translation approval coverage.

php artisan stringhive:audit [<hive>]

The command fetches every key registered in the hive, then regex-scans your codebase for static calls to trans(), __(), trans_choice(), @lang(), Lang::get(), and Lang::choice(). It diffs the two sets and reports:

• Missing — keys found in code but absent from the hive (you forgot to push)
• Orphaned — keys in the hive but never referenced in code (stale strings)
• Unapproved — translations that exist but haven't been approved yet (opt-in via --fail-on-unapproved)

vendor/, node_modules/, and storage/ are excluded automatically. Dynamic keys (arguments containing $ or {) are counted but skipped from the diff.

Options

Examples

# Run the audit
php artisan stringhive:audit my-app

# Machine-readable JSON (useful in scripts)
php artisan stringhive:audit my-app --format=json

# GitHub Actions annotations — appear inline in PR diffs
php artisan stringhive:audit my-app --format=github

# Fail CI if either list is non-empty
php artisan stringhive:audit my-app --fail-on-missing --fail-on-orphaned

# Fail CI if any locale has unapproved translations
php artisan stringhive:audit my-app --fail-on-unapproved

# Only check specific locales (e.g. your launch locales)
php artisan stringhive:audit my-app --fail-on-unapproved --locale=fr,de,es

# Allow up to 5% unapproved — useful mid-release when some strings are still in review
php artisan stringhive:audit my-app --fail-on-unapproved --min-approved=95 --locale=fr,de

Default table output:

Auditing hive: my-app
  API keys: 150
  Scanned: 312 files — 147 unique static keys (4 dynamic skipped)

 MISSING — 2 key(s) in code but not in the hive
+---------------------+------------------------------------+------+
| Key                 | File                               | Line |
+---------------------+------------------------------------+------+
| auth.session_expired| app/Http/Middleware/Authenticate.php| 34   |
| emails.verify.title | app/Mail/VerifyEmail.php (+1)      | 18   |
+---------------------+------------------------------------+------+

 ORPHANED — 3 key(s) in the hive but not in code
+------------------------------+-----------+
| Key                          | API File  |
+------------------------------+-----------+
| old.flash.success            | flash.php |
| pagination.previous_disabled |           |
| welcome.hero_subtitle        | home.php  |
+------------------------------+-----------+

JSON output shape:

{
  "hive": "my-app",
  "summary": {
    "api_total": 150,
    "code_total": 147,
    "files_scanned": 312,
    "dynamic_skipped": 4,
    "missing": 2,
    "orphaned": 3
  },
  "missing": [
    {
      "key": "auth.session_expired",
      "occurrences": [{ "file": "app/Http/Middleware/Authenticate.php", "line": 34 }]
    }
  ],
  "orphaned": [
    { "key": "old.flash.success", "file": "flash.php" }
  ],
  "unapproved": {
    "fr": { "approved": 1100, "total": 1245, "approved_percent": 88.4 },
    "de": { "approved": 1200, "total": 1245, "approved_percent": 96.4 }
  }
}

GitHub format emits ::warning annotations that appear inline in pull request diffs:

::warning file=app/Http/Middleware/Authenticate.php,line=34::StringHive: missing key "auth.session_expired"
::warning ::StringHive: orphaned key "old.flash.success" (file: flash.php)

CI/CD usage

A typical pipeline pushes strings on merge and pulls translations before a release:

# Push new source strings after a merge
- run: php artisan stringhive:push --conflict-strategy=keep

# Audit key parity — fail if anything is out of sync
- run: php artisan stringhive:audit --fail-on-missing

# Pull translated files before building the release
- run: php artisan stringhive:pull

To gate a release on translation approval, add an unapproved check on your release or deploy branch:

# Block the deploy if launch locales aren't fully approved
- run: php artisan stringhive:audit my-app --fail-on-unapproved --locale=fr,de,es --format=github

Use a token with Write for push and Read for pull. Audit only needs Read.