Laravel langsys/langsys-php-laravel
基于 langsys/langsys-php 的轻量级 Laravel 封装：包含 @t Blade 指令、t() 辅助函数以及语言环境中间件。代码中的短语既是查找键，也是基础语言的默认文本——无需键文件，也无需提取步骤。翻译在服务器端完成，因此页面送达时已完成本地化。
这是后端 SDK，因此本页没有浏览器内演练场——浏览器无法运行 PHP。演示应用是下方每个示例的在线版本：克隆它并运行 php artisan serve，或在 Codespace 中打开——这是一个真实的 PHP 容器，会为您完成安装并提供服务。完整的软件包参考（包括自动页面翻译和 Inertia 数据预填充）请见 Laravel SDK 文档。
正在使用 AI 编程智能体?把这段提示词交给它
Add Langsys translation to this Laravel app.
1. Read https://docs.langsys.dev/llms.txt, then follow
https://docs.langsys.dev/learn/sdk/laravel/ for the install and setup.
2. The English text in the code is the translation key. Wrap user-facing
strings as they are: no keys file, no extraction step, and no
hand-written plural or gender branches (Langsys generates those).
3. Read the Langsys project id and API key from environment variables.
The write key is for development and servers only; anything shipped
to the browser gets the read-only key.
4. Keep brand names and user-generated content out of translation.安装
composer require langsys/langsys-php-laravel
php artisan vendor:publish --tag=langsys-config# The server can hold a WRITE key — unlike a browser app, it's never
# shipped to visitors. A write key is what lets new phrases register.
LANGSYS_API_KEY=your-api-key
LANGSYS_PROJECT_ID=your-project-id还没有项目或密钥？快速入门两分钟即可帮你搞定。
中间件
两个中间件负责框架层面的工作:DetectLocale 解析访客的语言区域(依次为查询参数、Cookie、会话,然后是 Accept-Language)并保存其选择;FlushPendingRegistrations 会在响应发出之后将新发现的短语发送到 Langsys,因此注册过程绝不会拖慢页面。
// bootstrap/app.php (Laravel 11/12)
->withMiddleware(function (Middleware $middleware) {
$middleware->web(append: [
// Resolves ?locale= / cookie / session / Accept-Language,
// then persists the visitor's choice.
\Langsys\Laravel\Http\Middleware\DetectLocale::class,
// After the response is sent, registers any phrases
// rendered for the first time.
\Langsys\Laravel\Http\Middleware\FlushPendingRegistrations::class,
]);
})在 Blade 中翻译
只需一个指令:@t(phrase, category?, params?, locale?)。参数通过 {name} 标记进行插值——数字和日期会按区域设置格式化输出——并且输出内容会经过 HTML 转义。
<h1>@t('Welcome to our store', 'Home')</h1>
<p>@t('Hello, {name}! You have {count} new messages.', 'Greetings',
['name' => $name, 'count' => $count])</p>PHP 中的任何位置
@t 就是带转义功能的 t() 辅助函数——该辅助函数本身可在任何地方使用:控制器、Livewire 组件、作业、邮件、验证消息。
// Controllers, Livewire components, jobs, mail — anywhere:
$title = t('Order confirmed', 'Checkout');
$body = t('Your order {id} ships on {date}.', 'Checkout', [
'id' => (string) $order->number, // strings skip number formatting
'date' => $order->ships_at, // DateTime → locale-formatted
]);复数
直接写完整的句子即可:Langsys 会在翻译时为每种语言区域生成复数形式(包括基础语言区域),SDK 会渲染与您的数量相匹配的分支(通过 ext-intl 支持完整的 ICU)。所有 SDK 都是如此,因此短语可以在后端和前端之间通用。
// Written flat. Langsys generates each locale's plural forms during
// translation (the base locale included) and the SDK picks the branch.
t('You have {count} items in your cart', 'Cart', ['count' => $count]);Langsys 生成的复数形式自 langsys/langsys-php 1.3.2 起才会传递到 PHP;更早的版本对所有数量(包括 1)都会渲染复数形式。
性别一致
西班牙语、法语或俄语会根据所指的人对 {username} has been invited 进行屈折变化。Langsys 会在翻译时生成这些分支(与生成复数形式的方式相同),参数以变量名命名,并加上后缀 _gender:male、female 或 other。只要你知道性别,就请传入。工作原理,以及如何找出需要它的短语 →
{{-- Pass the agreement argument alongside the value it inflects. --}}
@t('{username} has been invited', 'Team', [
'username' => $post->author->name,
'username_gender' => $post->author->gender, // 'male' | 'female' | 'other'
])不知道性别？请显式传入 'other'——它是中性分支。即使缺少该值，基础 SDK 也会自动为您采用 other 分支（langsys/langsys-php 1.3.1 及更高版本，无论是否启用 ext-intl），因此句子仍能正确显示。
分类
类别用于限定短语的范围，因此相同的文字在不同的上下文中可以有不同的译法。
{{-- Same word, two meanings — the category disambiguates. --}}
<strong>@t('Home', 'Main Menu')</strong> {{-- "Inicio" --}}
<strong>@t('Home', 'Home repairs')</strong> {{-- "Casa" --}}统一的标记样式:{name}。在 JS SDK 中,markup 参数使用 %name%,因为单个花括号会与 JSX 和 Vue 模板语法冲突。Blade 不存在这种冲突,因此 PHP 领域处处使用规范的 {name} 形式——这与 t() 在每个 SDK 中使用的形式相同。
我该使用哪一个？
| 你正在翻译…… | 使用 | 为什么 |
|---|---|---|
| Blade 模板中的文本。 | @t(...) | t() 辅助函数加上 HTML 转义——可安全地直接用于模板输出。 |
| 其他任何位置的字符串——控制器、Livewire、作业、邮件。 | t() | 返回一个已插入参数并解析 ICU 复数的纯字符串。 |
| 绝不能翻译的内容——品牌名称、代码、ID。 | 保持不包裹 | 覆盖范围是明确的：只有你包裹起来的字符串才会被翻译；未标记的输出将原样透传。 |
| 一份你已有的、以字符串形式存在的完整 HTML 文档。 | Langsys::client()->translatePage() | 回落到原生 PHP SDK 的整页流水线——标题、meta 和正文文本一次调用即可完成。 |
经验法则:Blade → @t · PHP → t() · 无法改动的内容 → 不要包裹。
在服务器端发现词条
渲染一个 Langsys 尚未见过的短语时，它会先进入队列，并在响应结束后完成注册——访客会立即看到您的基础语言文本，而该短语会出现在您的控制台中，等待翻译。这需要写入权限的密钥；使用只读密钥时，队列会被静默跳过，这正是在不应修改目录的环境中所期望的行为。
与 JS SDK 配合使用
在使用 Inertia 或混合应用?把服务器已获取的目录交给 JS SDK,这样客户端就不必再次获取——这与前端 SDK 页面中介绍的 initialTranslations 传递方式相同。
// app/Http/Middleware/HandleInertiaRequests.php
use Langsys\Laravel\Support\InertiaSsrProps;
public function share(Request $request): array
{
return [...parent::share($request), ...InertiaSsrProps::share()];
}// resources/js — Vue shown; same shape for React/Svelte
import { LangsysApp, useLocaleStore } from 'langsys-js-vue';
const { store } = useLocaleStore(props.langsys.initialTranslationsLocale);
LangsysApp.init({
projectid: import.meta.env.VITE_LANGSYS_PROJECT_ID,
key: import.meta.env.VITE_LANGSYS_API_KEY, // read-only key on the client
UserLocaleStore: store,
initialTranslations: props.langsys.initialTranslations,
initialTranslationsLocale: props.langsys.initialTranslationsLocale,
});门面与原始客户端
Langsys 门面对应 t()，而 Langsys::client() 会为你提供底层的 langsys/langsys-php 客户端，用于短语查找之外的所有操作——读取目录、缓存控制、内容块。
use Langsys\Laravel\Facades\Langsys;
Langsys::translate('Save', 'UI'); // same seam as t()
Langsys::client()->getTranslations('es-es'); // the vanilla langsys/langsys-php client
Langsys::client()->clearCache('es-es'); // pick up dashboard edits before the TTL