> For the complete documentation index, see [llms.txt](https://quantumphp.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://quantumphp.gitbook.io/docs/packages/lang/usage.md).

# Usage

## Configure supported languages

Create `shared/config/lang.php` with the language settings the factory expects:

```php
return [
    'enabled' => true,
    'supported' => ['en', 'es'],
    'default' => 'en',
    'url_segment' => 1,
];
```

Practical notes:

* `enabled` controls whether web bootstrap loads translations automatically
* `supported` is the allowlist for query, URL, and header detection
* `default` is the required fallback when request detection yields no supported language
* `default` does not have to be present in `supported`; Quantum still uses it as the final fallback
* `url_segment` is the URL segment index used for language detection (for example, `1` for `/es/articles`)

## Add translation files

Place translation files under the shared resources directory:

```php
// shared/resources/lang/en/custom.php
return [
    'test' => 'Testing',
    'info' => 'Information about the {%1} feature',
];
```

Then read them with the file name plus key path:

```php
echo t('custom.test');
echo t('custom.info', ['new']);
```

## Add module-specific translations

Modules can ship their own translations under:

```
modules/<Module>/resources/lang/<lang>/
```

This works only when the current request is matched to a module route, because the translator uses `request()->getCurrentModule()` to build the module path.

## Use request-driven language detection

The package accepts three request-driven inputs:

### Query string

```
/articles?lang=es
```

### URL segment

With `url_segment => 1`:

```
/es/articles
```

### Accept-Language header

```http
Accept-Language: es, en;q=0.8
```

If none of those produce a supported value, Quantum uses `lang.default`.

## Use translations in application code

```php
$current = current_lang();

if ($current === 'es') {
    $label = t('custom.learn_more');
}
```

In views, `_t()` can output directly:

```php
<button><?php _t('custom.learn_more'); ?></button>
```

## Reload translations after a manual reset

```php
use Quantum\Lang\Factories\LangFactory;

$lang = LangFactory::get();
$lang->flush();
$lang->load();
```

Use this only when you intentionally need to clear the in-memory translation store. It is not a language-switching API, and it reloads the translator's original language selection.

## Caveats to keep in mind

* `setLang()` updates the visible language code, not the translator source language.
* Missing translation files fail loudly during `load()`, but missing keys do not.
* Only the active module is scanned for module translations during a request.
* Query and URL detection require an exact supported-language match; only the header fallback is normalized to a primary two-letter code.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://quantumphp.gitbook.io/docs/packages/lang/usage.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.