[3.x] Support localized pages

[emmadesilva]

Would be great if we on the framework level could support this now. I'm not sure how to best handle stuff like posts and Markdown and documentation pages, maybe they need to be prefixed with the language code and duplicate the files? I think the first step is to just support __('translation.keys') and run site build once for each language found/configured.

[emmadesilva]

ChatGPT Deep Research

Deep Research Report on Multi-Language Support for HydePHP v3

Executive summary

HydePHP is explicitly positioned as a content-first, Laravel-powered static site generator: its public docs and framework source show a build pipeline centred on source-file autodiscovery, Blade rendering, Markdown compilation, and static HTML output in _site, with development ergonomics provided by an Artisan-style CLI and a realtime preview server rather than by a long-lived web runtime. Blade pages are rendered during the build through Laravel’s view system, Hyde discovers content from _pages, _posts, and _docs, and the public documentation currently exposes HydePHP 2.x as the latest documented major release. That means the safest design for “HydePHP v3” localisation is not a request-time locale layer, but a build-time translation system that reuses Laravel conventions where they fit and adds only the minimum static-site-specific pieces Hyde needs. citeturn27view2turn7view0turn3view1turn3view2turn26search8turn26search2

The recommended design is: keep translations file-based inside the repository; adopt Laravel-style lang/ catalogues as the core storage format; treat PHP array files as the primary first-class format and JSON as a secondary first-class format; support YAML and TOML through import/export tooling rather than as equal-priority core runtime formats; render translations at build time by default; and use explicit locale URLs for multi-language sites, with optional root-only language suggestion or redirect logic for hosts that want it. This preserves Hyde’s static-first philosophy, keeps the default site fully cacheable, and avoids relying on Accept-Language as the primary selector, which both W3C guidance and static-site tooling ecosystems treat with caution. citeturn3view4turn14view1turn14view5turn13search16turn13search2

For authoring, the cleanest split is: use global language keys for shared UI and editable agency-managed text; use front matter only for page-owned metadata or local overrides; and keep long-form translated page bodies as actual Hyde content files rather than pushing them into language catalogues. Hyde already treats content files and front matter as first-class, and its front matter is YAML-based, so this division matches the framework’s existing ergonomics instead of fighting them. citeturn27view2turn3view3turn9search1

The practical API should feel Laravel-native. Hyde should expose build-aware __(), @lang, and trans_choice()-style usage in Blade, add a small set of static-specific helpers such as hyde_locale(), hyde_dir(), hyde_number(), and hyde_date(), and optionally register custom Blade directives for locale conditionals or safe JSON export to client scripts. Laravel localisation already defines the conventions for keyed PHP files, JSON translation files, interpolation, fallback locales, package overrides, and plural retrieval; Blade already supports custom directives and custom conditional directives, so Hyde can extend familiar primitives rather than inventing a parallel DSL. citeturn15view3turn14view5turn14view4turn15view2turn25view3turn25view0

For validation and operations, Hyde should add first-party CLI commands that mirror both HydeCLI and Laravel expectations: scaffold language files, add locales, extract keys, sync missing keys, validate placeholders and plural forms, export JS subsets, and report missing or fallback translations during build. Hyde already has build, rebuild, serve, validate, make:*, publish:*, and vendor:publish, while Laravel already publishes the lang directory and defines the override path for package language files. Hugo’s multilingual tooling adds one more useful precedent: explicit warnings and placeholders for missing or fallback translations. citeturn27view1turn15view0turn14view4turn16view0

HydePHP constraints and localisation principles

Hyde’s architecture strongly points toward localisation as a compile-time concern. Hyde’s quickstart and compile docs say the build scans source directories, discovers files, and compiles them into static HTML in _site; the framework service provider registers source and output directories for the built-in page types and discovers Blade views from the page source directory; and BladePage::compile() renders via Laravel’s View::make(...)->render(). Put simply: Hyde already has a deterministic render phase, and that render phase is the right place to inject locale state. A design that depends on per-request middleware or runtime route negotiation would add moving parts that Hyde does not currently need to ship finished pages. citeturn27view2turn7view0turn3view1

Hyde is also deliberately developer-friendly. Its docs emphasise that the HydeCLI is Artisan-based; it ships commands for build, rebuild, serve, validate, make:page, make:post, publish:views, and vendor:publish; and published views land in resources/views/vendor/hyde. Because of that, multi-language support should feel like another Hyde-first workflow, not an external package with undocumented bootstrapping. The most compatible developer experience is therefore “HydeCLI plus familiar Laravel localisation syntax”, not “bring your own i18n stack and wire it together by hand”. citeturn27view1turn27view0turn8search2

Hyde’s content model also shapes what should and should not go into language files. Static pages live in _pages; posts live in _posts; documentation pages live in _docs; page filenames map to output paths; and YAML front matter is optional but widely used for metadata such as titles and navigation labels. That makes language catalogues a good fit for UI strings, reusable snippets, and agency-editable copy blocks, while front matter remains the natural place for page-scoped metadata and source files remain the natural place for full content bodies. Moving whole pages into translation tables would cut across Hyde’s content-first model and make Markdown authoring worse instead of better. citeturn3view3turn3view2turn9search1

A final constraint is versioning reality. Public Hyde documentation presently centres on the 2.x line and HydePHP v2.0 release notes, while the framework repository shows the current architectural seams. I did not find a public 3.x documentation set to anchor a v3-only implementation contract, so the soundest recommendation is an additive, opt-in design that works with the documented v2 architecture and is clean enough to formalise in a future v3 release without breaking existing Hyde projects. citeturn26search8turn26search2turn3view0

flowchart LR
    A[Hyde source files<br>_pages _posts _docs] --> B[Autodiscovery]
    B --> C[Page models]
    D[lang catalogues<br>PHP arrays JSON] --> E[Locale-aware translator]
    C --> E
    E --> F[Blade render]
    E --> G[Markdown render]
    F --> H[_site output]
    G --> H
    I[HydeCLI build rebuild serve validate] --> E

Loading

The design principles that follow from those constraints are straightforward. Localisation should be opt-in; file-based; build-time by default; URL-explicit for public multilingual sites; Laravel-shaped at the API level; strict-but-helpful in validation; and minimal in client runtime unless a site explicitly asks for client-side access to translations. Those principles are what best fit Hyde’s present documented identity as a fast, deployable, static output framework powered by Laravel rather than a dynamic application server. citeturn27view2turn3view0turn24view0

Recommended architecture

The core recommendation is to introduce a dedicated localisation subsystem that runs entirely inside Hyde’s build and preview environments. Conceptually, Hyde would load locale configuration, normalise translation catalogues, establish a current locale for each render, expose Laravel-compatible translation helpers to Blade and Markdown render contexts, and emit already-localised HTML. For a single-language site, this means “language files as editable text keys”. For a multi-language site, it means “expand render output by locale and route strategy”. In both cases, the browser receives static HTML first, not a client-side translation bundle that must reconstruct the page after load. That is the closest match to Hyde’s existing build model and to static-site i18n guidance that prefers distinct URLs for language variants. citeturn27view2turn3view1turn13search2

For public URL strategy, Hyde should treat explicit locale URLs as the default for multi-language sites: either /en/... and /fr/... for all locales, or /... for the default locale plus /fr/..., /ar/..., and so on for secondary locales. Eleventy’s i18n guidance explicitly recommends language codes in URLs for static sites, and only suggests content negotiation on the root when needed. W3C’s guidance warns against using Accept-Language alone to determine locale. Together, those sources point to a clear default: locale-prefixed URLs for cacheability, SEO clarity, predictable sharing, and static hosting friendliness; optional root-only language suggestion or redirect as a convenience layer, not the primary mechanism. citeturn13search2turn13search16turn13search0

The fallback model should also be explicit and static-safe. Laravel documents both a default locale and a fallback locale, and Hugo’s multilingual docs show a practical lookup order that tries the current language first and then the default content language, with build-time warnings available for missing and fallback translations. Hyde should adopt the same spirit, but with one static-site refinement: resolve every missing key during the build, log it, and let projects choose between permissive fallback and strict failure. That keeps production HTML deterministic and makes missing text visible well before deployment. citeturn15view2turn16view0

A sensible fallback order for Hyde is:

1. exact filesystem locale, such as en_GB;
2. base language, such as en;
3. configured fallback locale;
4. literal key or configured placeholder, depending on strictness.

That order is not stated verbatim in Laravel’s docs, but it is a strong inference from Laravel’s default/fallback locale model and from Hugo’s exact-locale-then-default lookup pattern. In practice it solves the most common static-site case: region-specific copy can be partial, while a simpler base language catalogue carries the rest. citeturn15view2turn16view0

The best internal implementation path is to reuse Laravel-compatible translator semantics during the Hyde render rather than building a wholly separate Hyde-only translator. Laravel already documents keyed PHP files, JSON files, placeholder replacement, and trans_choice() plural lookup; Blade renders inside Hyde use Laravel’s view engine; and Blade itself is designed to be extended. So Hyde should present translation as a first-class build service layered onto the existing Blade/Markdown render flow, not as a second template engine. citeturn14view1turn14view5turn14view4turn3view1turn24view0

For strategy trade-offs, the table below captures the recommended stance. The factual background comes from Hyde’s static build model, Laravel’s localisation API, and static-site guidance on distinct URLs and content negotiation. citeturn27view2turn15view3turn13search2turn13search16

Strategy	Fit with Hyde	Strengths	Weaknesses	Recommendation
Pure build-time translation	Excellent	Zero runtime dependency for translated HTML; best CDN caching; predictable output; matches Hyde build model	More build work for many locales	Default
Client-side runtime translation	Poor to moderate	Useful for dynamic widgets	First render is untranslated or duplicated; extra JS/runtime state	Optional, JS-only subsets
Server/edge negotiation without locale URLs	Weak	Can feel automatic	Harder caching; poorer shareability; W3C cautions against relying on language headers alone	Avoid as primary model
Hybrid root negotiation + locale URLs	Good	Friendly first visit; static pages still cache by URL	Requires tiny JS or host redirects	Optional convenience layer

flowchart TD
    A[Load config/locales.php] --> B[Normalise locale tags and filesystem names]
    B --> C[Load PHP/JSON catalogues]
    C --> D[Build translation index and fallback map]
    D --> E[Discover Hyde pages]
    E --> F[Render each page in each required locale]
    F --> G[Record used keys and fallback hits]
    G --> H[Emit HTML with lang dir hreflang]
    G --> I[Emit optional JS locale payloads]
    H --> J[Validate missing keys and placeholders]
    I --> J

Loading

File formats and project layout

Laravel gives Hyde the strongest compatibility baseline for on-disk structure. Laravel stores keyed strings in files under lang/{locale}/... and supports JSON translation files located directly in lang/; it recommends ISO 15897-style locale directory names such as en_GB; it documents fallback locale configuration; and it warns about conflicts between JSON translation keys and PHP translation filenames. Hyde should inherit those conventions where practical, because they align with both Laravel developer expectations and package override conventions under lang/vendor/{package}/{locale}. citeturn14view1turn15view3turn15view2turn14view4

The wrinkle is that the web platform speaks BCP 47 language tags for lang and browser locale preferences, while Laravel’s filesystem naming guidance for territory-specific directories uses underscores. MDN documents the HTML lang attribute as a BCP 47 tag, and browser language preference APIs likewise return BCP 47 tags. The clean Hyde answer is therefore dual naming: keep Laravel-style filesystem names on disk, but store a canonical public locale tag in config and emit hyphenated BCP 47 tags into HTML, JS, and URLs. For example, filesystem en_GB maps to public tag en-GB. citeturn19search7turn19search0turn14view1

A recommended project layout looks like this:

config/
├── hyde.php
└── locales.php

lang/
├── en/
│   ├── site.php
│   ├── nav.php
│   └── forms.php
├── en_GB/
│   └── site.php
├── fr/
│   ├── site.php
│   └── nav.php
├── en.json
├── fr.json
└── vendor/
    └── hyde/
        └── fr/
            └── ui.php

_pages/
├── about.md
├── contact.blade.php
└── pricing.blade.php

_posts/
└── launch-day.md

_docs/
└── getting-started.md

That layout keeps the catalogue system close to Laravel while remaining obviously Hyde-shaped around _pages, _posts, and _docs. Hyde’s page discovery and output conventions already depend on those source directories, and Laravel already defines the lang/vendor/{package}/{locale} override path if Hyde or Hyde add-ons ship their own UI strings. citeturn7view0turn3view3turn14view4

The format choice should be opinionated. Laravel officially supports PHP arrays and JSON; Hugo shows that JSON, YAML, and TOML all work as translation table formats; the YAML spec confirms that YAML is indentation-sensitive and comment-friendly; and TOML’s spec emphasises that it is designed to map unambiguously to a hash table and supports comments. Based on those sources, Hyde should treat PHP arrays as the primary format, JSON as a secondary first-class format, and YAML/TOML as import-export formats handled by tooling. That gives agencies friendly options without making Hyde’s core locale loader support four equally privileged parsers and semantics. citeturn14view1turn15view3turn16view0turn17search1turn17search6

Format	What the sources say	Hyde fit	Recommendation
PHP arrays	Laravel’s canonical keyed-string format under lang/{locale}/file.php citeturn14view1	Best alignment with Laravel helpers and package overrides	Primary
JSON	Laravel supports locale JSON files directly in lang/, especially for many strings; caution on key/file conflicts citeturn15view3turn14view4	Good for flat string maps and editor tooling	Secondary first-class
YAML	Hugo supports YAML translation tables; YAML has comments and indentation-based mappings citeturn16view0turn17search1	Familiar to Hyde users because front matter is YAML, but easier to misformat and less Laravel-native	Tooling import/export
TOML	Hugo supports TOML translation tables; TOML is designed to map unambiguously to hash tables and supports comments citeturn16view0turn17search6	Pleasant for config-like structures, but uncommon in Laravel/PHP ecosystems	Tooling import/export

The other key layout question is “global keys or front matter?”. Hyde already uses front matter for page metadata, so front matter should remain page-scoped and metadata-oriented. Language files should hold reusable or agency-editable strings that may be referenced from multiple pages, templates, partials, and JS widgets. Long-form content should remain in content files. That gives teams a practical rule: if the string belongs to the page as metadata, keep it with the page; if it belongs to the site system or reusable copy inventory, put it in lang/; if it is real article or documentation content, keep it as Markdown or Blade content. citeturn3view3turn9search1turn3view0

A small configuration file can resolve the filesystem/public-locale split and define output strategy:

<?php

return [
    'default' => 'en-GB',
    'fallback' => 'en',
    'url_strategy' => 'prefix-except-default', // prefix-all | prefix-except-default | none
    'strict' => false,

    'supported' => [
        'en-GB' => [
            'filesystem' => 'en_GB',
            'name' => 'English (UK)',
            'dir' => 'ltr',
            'public' => true,
        ],
        'fr' => [
            'filesystem' => 'fr',
            'name' => 'Français',
            'dir' => 'ltr',
            'public' => true,
        ],
        'ar' => [
            'filesystem' => 'ar',
            'name' => 'العربية',
            'dir' => 'rtl',
            'public' => false,
        ],
    ],

    'js' => [
        'export' => true,
        'strategy' => 'namespaced',
        'namespaces' => ['search', 'filters'],
    ],
];

Recommended sample language files:

<?php
// lang/en/site.php

return [
    'brand' => [
        'name' => 'Northwind Studio',
        'tagline' => 'Fast, elegant websites for ambitious teams.',
    ],

    'cta' => [
        'primary' => 'Start your project',
        'secondary' => 'View our work',
    ],

    'footer' => [
        'contact' => 'Contact',
        'privacy' => 'Privacy policy',
    ],
];

<?php
// lang/en_GB/site.php

return [
    'footer' => [
        'privacy' => 'Privacy policy',
    ],

    'forms' => [
        'budget_label' => 'Budget',
        'budget_help' => 'Tell us roughly what you have budgeted.',
    ],
];

{
    "Get in touch": "Contact us",
    "Read more": "Read more"
}

And a Hyde page can keep only page-owned translation references in front matter:

---
title_key: pages.about.title
description_key: pages.about.description
navigation:
  label_key: nav.about
i18n:
  namespace: about
---
# About

That style is deliberately more robust than trying to execute translation expressions inside YAML front matter, while still letting layouts and page models resolve translated metadata during the build. It fits Hyde’s existing front matter usage and keeps content authors away from brittle template syntax in metadata blocks. citeturn3view3turn9search1

Template and JavaScript API examples

The template API should stay close to Laravel. Laravel documents __() for translation lookup, placeholder replacement using :name-style tokens, and trans_choice() for plural retrieval. Blade also allows custom directives and custom conditional directives via Blade::directive() and Blade::if(). Hyde should therefore expose Laravel-shaped helpers directly in Blade and supplement them with a few static-site-specific helpers rather than replacing the syntax authors already know. citeturn14view5turn14view4turn25view3turn25view0

Recommended Blade usage:

@extends('hyde::layouts.app')

@section('content')
    <main class="mx-auto max-w-6xl px-6 py-16">
        <h1>{{ __('pages.about.title') }}</h1>
        <p>{{ __('pages.about.summary') }}</p>

        <a href="{{ hyde_locale_url('contact') }}" class="btn">
            {{ __('site.cta.primary') }}
        </a>

        <p>
            {{ trans_choice('stats.projects_completed', $count, ['count' => $count]) }}
        </p>

        <p>
            {{ hyde_date($page->matter('date')) }}
        </p>

        <p>
            {{ hyde_number(12500.5, style: 'currency', currency: 'GBP') }}
        </p>
    </main>
@endsection

Recommended directives and helpers to ship:

@lang('site.footer.contact')

@choice('stats.projects_completed', $count, ['count' => $count])

@locale('fr')
    <a href="/fr/contact/">{{ __('site.cta.primary') }}</a>
@endlocale

@rtl
    <link rel="stylesheet" href="{{ asset('rtl.css') }}">
@endrtl

The rationale is straightforward. __() and trans_choice() align with Laravel; @lang is familiar Blade sugar; custom locale conditionals fit Blade’s Blade::if() extension model; and build-time helpers such as hyde_date() or hyde_number() keep localisation-logic out of page templates. citeturn14view5turn14view4turn25view3turn25view0

Pluralisation deserves an explicit design choice. Laravel’s documented plural syntax is pipe- and range-based and integrates with trans_choice(). That makes it the right core behaviour for Hyde’s first localisation release because it is immediately familiar to Laravel users and requires no new message syntax for the majority of agency and brochureware use cases. At the same time, Unicode’s CLDR plural rules and ICU MessageFormat are stronger foundations for languages with more plural categories and for complex message patterns. The pragmatic answer is: ship Laravel-style pluralisation in core for v1 of Hyde i18n, but design the translator contract so a future optional ICU backend can be plugged in later without changing template call sites. citeturn14view4turn12search1turn12search0

A Laravel-compatible core plural file might look like this:

<?php
// lang/en/stats.php

return [
    'projects_completed' => '{0} No projects completed yet|{1} :count project completed|[2,*] :count projects completed',
];

For date and number formatting, Hyde should do two different things depending on where formatting happens. When the value is known at build time, format in PHP using IntlDateFormatter and NumberFormatter, both of which are locale-sensitive and built for ICU-backed formatting. When the value is created or updated in the browser, use the platform Intl.DateTimeFormat and Intl.NumberFormat APIs in the current document locale. That gives static pages correct server-side output without adding JS, while still giving interactive widgets a standards-based client path. citeturn18search0turn18search1turn11search16turn11search1

RTL support should be built in at the document level. W3C’s bidi guidance says authors should set dir="rtl" on the html element whenever the overall document direction is right-to-left, and MDN documents lang as a BCP 47 language tag on HTML content. Hyde should therefore emit <html lang="ar" dir="rtl"> or equivalent from locale config, expose hyde_dir() to templates, and encourage theme authors to prefer CSS logical properties over hard-coded left/right assumptions. A locale-aware HTML shell is more important than clever per-string direction heuristics. citeturn11search6turn19search7

A recommended layout shell:

<!doctype html>
<html lang="{{ hyde_locale_tag() }}" dir="{{ hyde_dir() }}">
    <head>
        <title>{{ $title ?? __('site.brand.name') }}</title>
        @if (hyde_has_alternates())
            @foreach (hyde_alternate_locales() as $alternate)
                <link rel="alternate"
                      hreflang="{{ $alternate['tag'] }}"
                      href="{{ $alternate['url'] }}">
            @endforeach
        @endif
    </head>
    <body>
        @yield('content')
    </body>
</html>

For JavaScript, Hyde should resist the temptation to ship a full client translator by default. The right static-first model is one of two export patterns:

1. inline a tiny, page-scoped JSON payload for the keys that page’s JS needs; or
2. emit namespaced locale JSON files under a public asset path and fetch them from scripts that actually need them.

Blade already documents safe patterns for rendering arrays into JSON in scripts, and browser locale APIs expose navigator.languages for optional client-side locale preference inspection. That makes JS access feasible without turning the entire site into a runtime-translated app. citeturn24view0turn19search0

Inline subset pattern:

<script type="application/json" id="hyde-lang">
{!! json_encode(hyde_lang_export([
    'search.placeholder',
    'search.no_results',
    'filters.clear',
])) !!}
</script>

<script type="module">
    const strings = JSON.parse(document.getElementById('hyde-lang').textContent);
    const t = (key, fallback = key) => strings[key] ?? fallback;

    document.querySelector('#search').setAttribute('placeholder', t('search.placeholder'));
</script>

External namespaced pattern:

const locale = document.documentElement.lang;
const res = await fetch(`/assets/lang/${locale}/search.json`);
const strings = await res.json();

const t = (key, fallback = key) => strings[key] ?? fallback;

Optional root-only preference logic can then be tiny and isolated:

const preferred = navigator.languages?.[0] ?? navigator.language;

That should only ever be used on the root entry point, and only as a suggestion or configurable redirect, because the public site should still resolve to stable locale URLs for sharing and caching. citeturn19search0turn13search16turn13search2

flowchart TD
    A[Template calls __ trans_choice hyde_date] --> B[Build-time translator]
    B --> C[Interpolate placeholders]
    B --> D[Apply fallback]
    C --> E[Emit localised HTML]
    D --> E
    E --> F[Optional page-scoped JSON export]
    F --> G[Lightweight client scripts only when needed]

Loading

Tooling, build pipeline, and migration

Hyde’s CLI story is already one of its biggest strengths, so localisation should arrive as a family of HydeCLI commands rather than as a grab-bag of config-only features. Hyde documents build, rebuild, serve, validate, make:page, make:post, publish:views, and vendor:publish, while Laravel documents lang:publish for scaffolding the lang directory. That strongly suggests a Hyde-localisation command surface that feels both Hyde-native and Laravel-familiar. citeturn27view1turn15view0

Recommended commands:

Command	Purpose
php hyde lang:publish	Create config/locales.php and scaffold lang/
php hyde lang:add fr --from=en	Add a locale by copying a source locale
php hyde lang:extract	Scan Blade, Markdown, and front matter references to produce or update key inventories
php hyde lang:sync --locale=fr	Add missing keys from the source locale without overwriting translated values
php hyde lang:validate --strict	Detect missing keys, placeholder mismatches, plural-format issues, and locale-tag naming problems
php hyde lang:export-js	Produce page or namespace scoped JSON payloads for client scripts
php hyde lang:import --format=yaml	Convert YAML/TOML translator-friendly files into canonical PHP/JSON files
php hyde build --locale=fr	Build only one locale
php hyde rebuild _pages/about.blade.php --locale=fr	Rebuild one page for one locale
php hyde build --i18n-report	Emit missing/fallback translation report during build

Those commands fit Hyde’s documented workflow patterns and borrow the best conventions from Laravel and Hugo. Laravel provides the “publish language files” precedent and package override model, Hugo provides a precedent for missing/fallback warnings during build, and Hyde already has both rebuild and validate, which are ideal anchors for incremental and strict localisation workflows. citeturn27view1turn15view0turn16view0

On the build-pipeline side, Hyde should make localisation dependency-aware. Blade templates are compiled and cached until modified, and Hyde already has a single-file rebuild command. A locale-aware build can extend that model: hash source files, templates, front matter, and the subset of translation keys each page actually used; when a language file changes, only rebuild the pages and locales that depend on those keys. For first implementation simplicity Hyde can rebuild per locale namespace or per locale file; later it can become key-level precise by recording resolved key usage during render. That is not something Hyde documents today, but it is a natural extension of the existing rebuild workflow and Blade cache model. citeturn27view1turn24view0

A robust build sequence would look like this:

1. Load locale config and normalise filesystem/public locale identifiers.
2. Load catalogues and calculate hashes by locale and namespace.
3. Discover Hyde pages and determine which locales each page should be rendered for.
4. Render pages under locale context, logging any used keys and fallback hits.
5. Emit localised HTML, alternate links, and optional JS payloads.
6. Run validation: missing keys, placeholder mismatches, JSON/PHP key collisions, locale naming issues, and untranslated fallback usage.
7. Fail or warn depending on strictness settings.

That sequence keeps translation concerns inside Hyde’s build loop rather than bolting on a second pass after HTML generation. It also makes serve and rebuild capable of showing missing-translation information during local development, which is much friendlier than discovering it only in CI. citeturn27view1turn21search1turn16view0

For CI, Hyde already has an official GitHub Action that can build full Hyde projects or anonymous Markdown/Blade projects and can publish artifacts or deploy to GitHub Pages. Localisation validation should simply become one more step in that pipeline: run php hyde lang:validate --strict, then php hyde build, then upload or deploy the artefacts. That keeps CI optional, but when used it remains entirely aligned with Hyde’s existing deployment story. citeturn10search0turn10search1turn10search2

A sensible migration path for existing Hyde sites is incremental rather than all-at-once:

1. publish or override the root layout if necessary so the site can emit lang and dir; Hyde already documents publish:views for this;
2. scaffold lang/ and set a default locale even for single-language sites;
3. replace repeated hard-coded UI strings in Blade views with __() calls;
4. move shared nav, footer, CTA, and form copy into language files;
5. add page-owned metadata keys such as title_key or description_key only where central editorial control is helpful;
6. enable validation in local development and CI before adding any second locale. citeturn27view0turn15view0turn27view1

Example migration from a current Hyde Blade page:

<h1>Contact us</h1>
<p>Tell us about your project.</p>
<a href="/about/">About</a>

to a localisation-ready version:

<h1>{{ __('contact.title') }}</h1>
<p>{{ __('contact.intro') }}</p>
<a href="{{ hyde_locale_url('about') }}">{{ __('nav.about') }}</a>

And for a current Markdown page with YAML front matter:

---
title: About
description: Learn more about our studio.
---

migrate only when central keying is useful:

---
title_key: pages.about.title
description_key: pages.about.description
---

That migration path matters because Hyde sites often start small. Laravel’s JSON translation mode is explicitly recommended when applications have a large number of translatable strings, but single-language Hyde sites often just need a modest catalogue of editable text keys for freelancers or agencies. So Hyde should make the “single locale, centralised keys” case excellent first, and let multi-locale expansion come second. citeturn15view3

Risks and compatibility

The biggest compatibility risk is overreaching on formats. Supporting PHP arrays and JSON directly is low-risk because it matches Laravel. Supporting YAML and TOML as equal-priority runtime formats is much riskier: Hyde would need more parser dependencies, more conversion rules, more edge cases around types and key shapes, and a more complex support matrix. Since Hyde already uses YAML for front matter, teams who love YAML can still use it through import/export tooling without forcing the core localisation loader to become a four-format parser surface. citeturn14view1turn15view3turn17search1turn17search6

Another real risk is silent key ambiguity. Laravel explicitly warns that JSON translation keys can conflict with translation filenames, and that such conflicts can produce unexpected translator behaviour. Hyde should therefore validate for namespace/file collisions, discourage mixing “JSON literal-string keys everywhere” with deep PHP namespace trees in the same domain, and give projects a single canonical source locale that all other locales sync from. If Hyde skips that validation, debugging catalogue behaviour will be frustrating. citeturn14view4

Locale naming itself is also a trap. Laravel’s directory guidance uses en_GB, while HTML and browser APIs use en-GB. If Hyde lets those leak into templates or URLs interchangeably, projects will accumulate subtle bugs around lang, asset paths, alternate links, and JS locale lookups. The mitigation is simple: one configured canonical public tag, one configured filesystem alias, automatic normalisation in the build, and a validator that rejects mixed use. citeturn14view1turn19search7turn19search0

Public locale negotiation can easily damage caching and user control if designed badly. MDN explains what Accept-Language is for, but W3C warns that it should not be used alone to determine locale. Static-site practice from Eleventy also pushes toward explicit language-coded URLs. So Hyde should not make header-driven or opaque cookie-driven negotiation its main story. The safer approach is explicit URLs plus an optional, user-respectful root convenience layer. citeturn13search0turn13search16turn13search2

Build cost grows with locale count. A site that renders 500 pages in one language may need to render 1,500 or 2,000 pages when several public locales are enabled, and any locale-aware search indexes, sitemaps, or JS bundles will grow alongside them. Hyde cannot remove that multiplication, but it can mitigate it with per-locale build filters, dependency-aware rebuilds, and optional visibility flags so not every configured locale must be public from day one. Hyde’s documented rebuild command and existing validation/build pipeline make those mitigations feasible. citeturn27view1turn27view2

RTL support can also surface theme assumptions that have nothing to do with the translator. W3C’s authoring guidance makes document direction a markup concern, not merely a CSS toggle. If Hyde adds locale support but bundled or user themes still rely on hard-coded margin-left, right: 0, or arrow icon directions, translations will technically work while layouts remain visually wrong. Hyde should therefore treat locale metadata and directional theming as linked concerns, document the need for logical CSS, and provide simple hyde_dir() or @rtl hooks to make theme adaptation easy. citeturn11search6turn11search3

The table below summarises the main compatibility hazards and mitigations described above. The hazards are grounded in the cited Laravel, W3C, MDN, and Hyde references; the mitigations are the recommended Hyde design responses. citeturn14view4turn14view1turn13search16turn13search2turn11search6

Risk	Why it matters	Mitigation
JSON key / filename collision	Can return unexpected translation data	Add lang:validate collision checks; prefer PHP namespaces for system copy
en_GB vs en-GB mismatch	Breaks HTML tags, URLs, or JS lookups	Separate filesystem alias from public locale tag
Overuse of language files for long content	Fights Hyde’s content-file model	Keep long-form content in _pages, _posts, _docs
Header-only locale negotiation	Poor user control, worse static caching	Use explicit locale URLs; root-only suggestion or redirect at most
Equal-priority YAML/TOML runtime support	Larger parser and support surface	Canonicalise to PHP/JSON; use import/export tooling
Locale-count build explosion	Slower builds, larger artefacts	Per-locale build flags, dependency-aware rebuilds, namespace hashing
RTL-only partially supported by theme	Localised text but broken layout	Emit correct dir; provide helpers; document logical CSS

From a backwards-compatibility standpoint, the safest rollout is fully opt-in. Existing Hyde sites should be able to ignore lang/ entirely and continue building exactly as before. Once a site introduces locale config or translation helper calls, Hyde turns on the localisation subsystem for that project only. That preserves Hyde’s “minutes to first site” simplicity while still enabling a serious multilingual pipeline for agencies, freelancers, and documentation teams when they need it. citeturn27view2turn3view0

[emmadesilva]

ChatGPT Sol High - Followup after I clarified constraints

Recommended model

Treat locale as a build-time dimension of the site. One php hyde build command should produce several completely static URL trees. The browser never chooses or loads translations; a language switcher is just a collection of ordinary links.

The important distinction is:

• Language files translate reusable strings: navigation, buttons, headings, agency-managed copy, form labels, theme strings.
• Localized content files translate authored content: posts, Markdown pages, documentation, front matter, titles, excerpts, and potentially slugs.

Laravel already provides the right catalogue conventions: lang/{locale}/*.php, JSON translations, config/app.php locale and fallback locale, __(), parameters, and trans_choice(). Hyde should use those directly rather than wrapping them in a Hyde-specific translation API. ([Laravel]1)

Minimal configuration

I would add only one Hyde setting:

// config/hyde.php

'locales' => [
    'en',
    'sv',
],

Then continue using Laravel’s existing settings:

// config/app.php

'locale' => 'en',
'fallback_locale' => 'en',

The behavior would be:

• An empty hyde.locales means localization routing is disabled.
• Language files still work on single-language sites.
• app.locale identifies the default site language.
• app.fallback_locale applies only to missing translation keys, not missing pages.
• Locale directory names must be registered, so Hyde can distinguish _pages/sv/ from an ordinary directory named sv.

A separate config/locales.php would be unnecessary for the first implementation. Optional metadata such as native language names could be added later without making it mandatory.

Single-language sites

Nothing changes structurally:

lang/
└── en/
    ├── site.php
    └── navigation.php

_pages/
├── index.blade.php
└── about.md

// lang/en/site.php

return [
    'hero' => [
        'title' => 'Websites that move your business forward.',
        'button' => 'Start a project',
    ],
];

<h1>{{ __('site.hero.title') }}</h1>

<a href="/contact">
    {{ __('site.hero.button') }}
</a>

This compiles exactly once to the existing routes. Simply adding lang/en must not enable locale prefixes or alter output paths.

That makes the agency use case excellent without forcing users to think of their site as “multilingual.”

Multilingual source layout

I would keep the default locale in the existing source locations and prefix only additional locales:

lang/
├── en/
│   ├── site.php
│   └── navigation.php
└── sv/
    ├── site.php
    └── navigation.php

_pages/
├── index.blade.php
├── about.md
├── contact.blade.php
└── sv/
    ├── index.blade.php
    ├── about.md
    └── contact.blade.php

_posts/
├── 2026-07-12-launch.md
└── sv/
    └── 2026-07-12-lansering.md

_docs/
├── 2.x/
│   ├── index.md
│   └── installation.md
└── sv/
    └── 2.x/
        ├── index.md
        └── installation.md

The compiled site becomes:

_site/
├── index.html
├── about.html
├── contact.html
├── posts/
│   └── launch.html
├── docs/
│   └── 2.x/
│       └── installation.html
└── sv/
    ├── index.html
    ├── about.html
    ├── contact.html
    ├── posts/
    │   └── lansering.html
    └── docs/
        └── 2.x/
            └── installation.html

So the public URLs are:

/about
/sv/about

/posts/launch
/sv/posts/lansering

/docs/2.x/installation
/sv/docs/2.x/installation

The locale should be the outermost URL dimension, even though each Hyde page type has its own output directory.

Why the default locale should remain unprefixed

I would not make /en/ the default behavior.

Keeping the default language unprefixed means:

• Existing URLs do not change when a second language is added.
• Existing content files do not need to be moved.
• The site root remains a real homepage rather than a generated redirect.
• A currently deployed Hyde site can add _pages/sv/ incrementally.
• GitHub Pages and similar hosts need no special redirect configuration.

An optional setting could support fully symmetrical URLs:

'prefix_default_locale' => true,

That mode could generate /en/..., /sv/..., and a root redirect using the same mechanism as versioned documentation. It should not be the default.

Do we actually run the build once per language?

Conceptually yes, operationally no.

Users should run:

php hyde build

Internally, Hyde should build locale-scoped page groups:

Discover all source variants
        ↓
Build default locale pages
        ↓
Build Swedish locale pages
        ↓
Generate locale-specific aggregate outputs
        ↓
Generate cross-locale metadata and links

This is better than invoking the complete builder as several disconnected processes because Hyde needs a global view of the site to generate:

• Equivalent-language links
• hreflang tags
• Language switchers
• Per-locale navigation
• Per-locale post indexes and feeds
• Per-locale documentation sidebars
• Per-locale and per-version documentation search indexes
• Route-collision validation

Before compiling each page, Hyde sets the Laravel locale:

App::setLocale($page->getLocale()->code);

Then Blade, BladeDown, components, layouts, and translation helpers naturally render the correct strings into the static HTML.

Reusing the versioned-documentation architecture

The new documentation implementation is a very good model. It introduces:

• A small DocumentationVersion value object
• A DocumentationVersions registry
• Prefix detection from identifiers and route keys
• Equivalent-route lookup
• Version-specific configuration matching
• Per-version sidebars and search indexes
• A generated entry point for the default version

It also ensures that each registered version gets isolated generated resources, while unversioned content is deliberately handled rather than silently mixed into the output.

Locales should reuse that pattern, but at a lower, site-wide layer:

Locale
Locales
LocaleContext
LocalizedRoute

Potential API:

Locales::enabled();
Locales::all();
Locales::default();
Locales::current();

Locales::fromSourcePath($path);
Locales::fromRouteKey($routeKey);

Locales::getEquivalentRoute($page, $targetLocale);

And on pages:

$page->getLocale();
$page->getTranslationKey();
$page->getLocalizedIdentifier();

The version implementation finds equivalent pages by removing the current version prefix and looking for the same path in the target version. Locale switching can do the same thing.

One important architectural difference

Documentation versions belong to one page type. Locales belong to all page types.

Locale parsing should therefore happen before the page type interprets the remainder of the source identifier:

_docs/sv/2.x/getting-started.md
      │
      ├── locale: sv
      └── documentation identifier: 2.x/getting-started
                                   │
                                   └── version: 2.x

The final route becomes:

sv/docs/2.x/getting-started

This makes locales and documentation versions composable instead of requiring special-case logic throughout DocumentationPage.

The versioned-docs implementation already demonstrates why preserving the dimension prefix through flattened route generation matters. Locale handling should generalize that idea.

Posts, Markdown, and documentation should be duplicated

For long-form content, separate files are the correct primitive.

A translated article is not merely a set of string substitutions. Its translation may need different:

• Headings
• Paragraph structure
• Links
• Images
• Examples
• Excerpts
• Publication metadata
• Search keywords
• Slug
• Navigation label

Putting complete Markdown documents into lang arrays would make Hyde less content-first.

For example:

_posts/2026-07-12-launch.md
_posts/sv/2026-07-12-lansering.md

Each file owns its translated front matter and Markdown.

The same applies to documentation:

_docs/2.x/installation.md
_docs/sv/2.x/installation.md

For pages made almost entirely from translation keys, the localized source files can be tiny wrappers around a shared view:

{{-- _pages/contact.blade.php --}}
@include('pages.contact')

{{-- _pages/sv/contact.blade.php --}}
@include('pages.contact')

The actual shared view uses __(), so there is no meaningful code duplication. A later enhancement could allow one page source to declare that it should be emitted for multiple locales, but that does not need to block the explicit and predictable v3 implementation.

Matching translations of the same page

The normal convention should be matching locale-relative identifiers:

_pages/about.md
_pages/sv/about.md

These naturally form one translation group.

Translated slugs need an explicit stable identifier:

---
title: Om oss
translation_key: about
slug: om-oss
---

Then Hyde can understand that these routes are equivalent:

/about
/sv/om-oss

Without translation_key, the identifier within the locale should be the implicit key.

This same key can power:

• Language switcher links
• hreflang
• Alternate URLs in the sitemap
• Missing-translation reports
• Cross-locale next/previous documentation links

The version switcher already uses equivalent-route lookup and falls back to the target version’s homepage when the equivalent page does not exist. A language switcher could use the same behavior, though it must never generate a nonexistent translated page.

Missing content versus missing strings

These need different rules.

Missing translation string

Use Laravel fallback behavior:

sv key
  ↓ missing
en fallback key
  ↓ missing
literal translation key

Hyde should report fallback usage during the build, with an optional strict mode.

Missing translated content file

Do not silently compile the English Markdown body at a Swedish URL.

If this exists:

_pages/about.md

but this does not:

_pages/sv/about.md

then /sv/about should not exist unless the author deliberately defines it.

The language switcher can link to /sv/, or show Swedish as unavailable on that page. This avoids producing pages whose navigation is Swedish while their main content is English.

Locale-scoped generated content

Every generated collection must be locale-aware.

For posts:

/posts
/posts/feed.xml

/sv/posts
/sv/posts/feed.xml

The Swedish post listing must contain only Swedish posts.

For documentation with two locales and two versions:

/docs/1.x/search.json
/docs/2.x/search.json

/sv/docs/1.x/search.json
/sv/docs/2.x/search.json

The versioned-docs diff already creates separate search indexes and search pages per version. Localization generalizes this to the cross-product of locale and version.

Similarly:

sidebar(locale=en, version=1.x)
sidebar(locale=en, version=2.x)
sidebar(locale=sv, version=1.x)
sidebar(locale=sv, version=2.x)

This is why locale cannot just be a string used while rendering templates. It must be part of page identity and generated collection identity.

Generated HTML

Every compiled page should include:

<html lang="sv">

and, where relevant:

<link
    rel="alternate"
    hreflang="en"
    href="https://example.com/about"
/>

<link
    rel="alternate"
    hreflang="sv"
    href="https://example.com/sv/om-oss"
/>

Only existing equivalents should be emitted. Google recommends that localized variants identify themselves and their other variants, using fully qualified alternate URLs. ([Google for Developers]2)

This can all be generated at compile time. No JavaScript or request-time language detection is needed.

Recommended v3 scope

For the first release, I would ship:

1. Laravel-native language files and helpers.
2. One hyde.locales configuration list.
3. Default-locale sources in their existing locations.
4. Non-default Markdown, post, and documentation variants in locale-prefixed directories.
5. Locale as a first-class property of pages and routes.
6. Per-locale navigation, feeds, indexes, and documentation resources.
7. Equivalent-route matching by relative identifier or translation_key.
8. Static language-switcher links and hreflang.
9. Build warnings for missing keys, invalid locale directories, and route collisions.
10. No automatic content fallback and no frontend localization runtime.

The central design is:

Language files translate interface and reusable copy.
Content files translate pages.
Locales are resolved during the build.
The output is ordinary static HTML in ordinary static directories.

That follows Laravel conventions while still behaving like Hyde rather than like a Laravel web application.