Lang English Laravel Package

Getting Started

This package is not a library you call — it is the bundled en locale data that ships with every Flarum install. flarum/core pulls it in transitively, so in most projects you will never composer require it directly. Verify it is present with:

composer why flarum/lang-english

Look here first: vendor/flarum/lang-english/locale/en.yml. That single YAML file is the authoritative catalogue of every core translation key you can reference from PHP, JS, or an extension. Grep it before inventing a string:

grep -n "sign_up" vendor/flarum/lang-english/locale/en.yml
grep -rn "^  [a-z_]*:" vendor/flarum/lang-english/locale/en.yml | head -50

First use case: you are building an extension and need a label. Instead of hardcoding "Save Changes", add your own key under your extension namespace, then fall back to en when a translation is missing. The second most common first use case is overriding a core string (e.g. renaming "Discussions" to "Threads") without forking Flarum.

Minimal loop:

1. Write the key and English value into your extension's locale/en.yml.
2. Call it via app.translator.trans() in JS or $this->translator->trans() in PHP.
3. Run php flarum cache:clear and hard-refresh the browser.

If a key renders as the raw key name (my-ext.admin.title) instead of text, the key does not exist in the active locale or the fallback — which is a fast, reliable smoke test.

Implementation Patterns

Extension-owned strings. Flarum loads every enabled extension's locale/en.yml. Use your extension ID as the top-level YAML namespace and call keys with that prefix:

# extensions/my-extension/locale/en.yml
my-extension:
  admin:
    settings:
      heading: Notification settings
      help: Choose which events send an email. Sent to {username}.

// PHP: service provider / controller
$label = $this->translator->trans('my-extension.admin.settings.heading');
$text  = $this->translator->trans('my-extension.admin.settings.help', ['username' => $user->display_name]);

// JS: component
app.translator.trans('my-extension.admin.settings.heading');
app.translator.trans('my-extension.admin.settings.help', { username: app.session.user.username() });

Placeholders are contract, not prose. {username} is substituted at render time. Never translate, reorder into a different token, or drop a placeholder — a missing placeholder produces a blank or a literal brace in the UI. Keep them intact in every language pack.

Overriding a core string. Ship a locale file from a small extension (or a custom lang pack) that reuses the core namespace and only the keys you want to change. Because extension locale resources are registered after core, the later value wins for the same key. This is the supported alternative to editing vendor/. Verify after each Flarum upgrade — core keys are renamed occasionally and a stale override will silently stop applying.

Building a full language pack. Copy the structure of vendor/flarum/lang-english/locale/en.yml, translate values only, never keys, and declare the locale in composer.json so Flarum's locale manager can discover it:

{
  "name": "acme/lang-french",
  "type": "flarum-extension",
  "extra": {
    "flarum-locale": { "code": "fr" }
  }
}

Then validate coverage with a key-diff against upstream en.yml before publishing.

Namespace discipline in code. In PHP, always go through the injected Translator rather than __()-style helpers; Flarum's translator carries the locale/fallback state. In JS, always app.translator.trans(...) rather than string literals, even for admin-only UI — it is what makes your extension translatable by third parties for free.

Missing-key audit in CI. A small script that extracts trans('...') calls from src/ and js/src/ and diffs them against your locale/en.yml catches the most common review nit: a key added in a JSX component but never added to YAML.

Gotchas and Tips

• READ ONLY subtree split. This repository is generated. Pull requests against it are closed or overwritten on the next split; core translation changes belong in the upstream Flarum monorepo (flarum/framework). Same applies to any patch you are tempted to make to vendor/flarum/lang-english/ — composer install wipes it.
• Version-lock to core's major. The locale package moves with Flarum's release cadence; a ^1.0 constraint against a Flarum 2 install will resolve to stale or absent keys. Let flarum/core choose the version rather than requiring it yourself.
• YAML footguns are the #1 source of "broken" translations. Quote any value containing :, #, or starting with {, [, *, &, @, `. yes, no, on, off parse as booleans — quote them. Tabs are illegal; use spaces. A YAML parse error usually surfaces as a blank page or missing bundle, not a friendly message.
• Cache is sticky. Translations are compiled into the locale cache/asset payload. After editing locale/en.yml, run php flarum cache:clear; in production, also republish assets if your deploy bundles them. A browser hard-refresh is often needed because the locale payload is cached client-side.
• Fallback hides mistakes. A key missing from your French pack silently renders in English because en is the fallback locale. That is good for users, bad for QA — test with the fallback disabled or diff keys explicitly.
• Raw key rendering means "not found." Seeing my-ext.foo.bar in the UI is not a template bug; it is Flarum telling you the key is absent from both active and fallback catalogues.
• Key collisions across extensions. Two extensions both defining a top-level notifications: block will clobber each other. Always prefix with the extension ID (my-extension:), never with generic words.
• HTML in translations is rendered, not escaped, in some UI paths. <b>, <a> and similar tags do appear in core strings, but injecting user data into an HTML-bearing translation is an XSS vector. Pass user content through placeholders only.
• Pluralization behavior differs between Flarum 1.x and 2.x (legacy |-style vs. ICU-style messages). Test a {count} string on the exact core version you target rather than assuming portability.
• New core keys do not exist here first. If you need a string Flarum does not have, put it in your extension's locale file — do not wait for a core release, and do not add it to this package.