README

……为 F3 多语言版本！

此插件为 Fat-Free 框架提供了一种对网站/应用程序进行本地化的URL友好方法。

演示：这里.

基本用法
根 URL
高级用法
重定向
迁移模式
严格模式
透传模式
API
潜在改进

基本用法

步骤 1

在 MULTILANG.languages 变量中声明您的应用程序的语言

$f3->set('MULTILANG.languages',array(
  'en' => 'en-GB,en-US,en',
  'ja' => 'ja-JP,ja',
  'es' => 'es-ES,es'
));

可以使用以下语法在配置文件中实现相同的声明

[MULTILANG.languages]
en = en-GB, en-US, en
ja = ja-JP, ja
es = es-ES, es

注意 1：每个条目将语言标识符（en、ja、es）映射到一个或多个区域设置。语言标识符是任意的（english、en-GB、japan等），但请记住：它们将出现在您的 URL 中。

注意 2：定义的第一个语言被视为主要语言，这意味着它被设置为 FALLBACK。在我们的示例中，在日语页面上，区域设置和字典将按以下顺序搜索：ja-JP、ja、en-GB、en、en-US。

注意 3：强烈建议在区域设置列表中包含一个与国家无关的语言代码（en、ja、es等）以提高浏览器语言检测。

步骤 2

通过实例化类启动插件，在调用 $f3->run 之前

$f3->config('config.ini');
Multilang::instance();
$f3->run();

就这样！

现在，每个现有的 URL 都已按您声明的语言数量进行了复制，使用标识符作为前缀

         => /en/contact
/contact => /ja/contact
         => /es/contact

原始 URL 呢？ => 它们已被删除。
原始根 / 呢？ => 它自动检测浏览器语言。见下文

根 URL

默认情况下，根 URL 自动检测浏览器语言并将其重定向到其根页面。

在我们的示例中，西班牙用户将被重定向到 /es，而俄罗斯用户将被重定向到 /en（回退到主要语言）。

您可以通过将 MULTILANG.root 设置为自定义处理程序来覆盖此默认行为

[MULTILANG]
root = App\MyRoot

用例：显示包含可用语言列表的启动页面。

高级用法

（需要使用路由别名）

重写 URL

每个翻译后的 URL 都由一个语言标识符后跟原始 URL 组成

/es + /terms-and-conditions = /es/terms-and-conditions

您可以通过设置 MULTILANG.rules 变量来自定义第二部分。例如，为了翻译上面的西班牙语 URL，您可以编写（假设路由名为 terms）

$f3->set('MULTILANG.rules',array(
  'es' => array(
    'terms' => '/terminos-y-condiciones'
  )
));

可以使用以下语法在配置文件中实现相同的声明

[MULTILANG.rules.es]
terms = /terminos-y-condiciones

从路由中排除语言

在翻译网站时，您可能需要逐路由进行渐进式翻译。也可能发生某些部分根本不会本地化（例如博客）。

为此，您可以通过将其设置为 FALSE 来删除特定语言的路由

[MULTILANG.rules.es]
blog = FALSE

对 /es/blog 的请求将返回 404 错误。

全局路由

有些路由必须保持语言无关性，例如验证码不需要本地化。此外，后台办公室通常也是单语的。

这些全局路由不会被重写：它们保留原始URL。它们使用MULTILANG.global变量定义

[MULTILANG]
global = captcha
;could also be an array:
global = alias1, alias2, alias3, /admin, /foo/bar

每个条目都可以是路由别名或URI前缀。

注意：全局路由默认自动检测语言。因此，在单语后台办公室的情况下，您可能需要在控制器级别强制设置语言。

重定向

如果您正在使用命名路由...

$f3->reroute将按预期工作，也就是说，它将重定向到提供的命名路由的当前语言URL。例如

$f3->reroute('@contact'); // OK => reroute to /xx/contact where xx is the current language

如果您正在使用无名称路由...

在这种情况下，您必须向$f3->reroute提供带语言前缀的URL

$f3->reroute('/en/contact'); // OK
$f3->reroute('/contact'); // Error => 404 Not Found

如果您希望将短URL提供给框架并让框架自动使用当前语言前缀URL，请使用插件提供的$ml->reroute方法

$ml->reroute('/en/contact'); // OK
$ml->reroute('/contact'); // OK => reroute to /xx/contact where xx is the current language

在您希望快速本地化具有无名称路由的现有项目，并且希望避免将每个$f3->reroute重写为$ml->reroute的情况下，您可以使用框架的ONREROUTE钩子

$f3->set('ONREROUTE',function($url,$permanent) use($f3,$ml){
  $f3->clear('ONREROUTE');
  $ml->reroute($url,$permanent);
});

// then in your controller, existing reroutes will keep on working:
$f3->reroute('/contact'); // OK => reroute to /xx/contact where xx is the current language

迁移模式

当翻译现有的单语站点时，将旧的单语URI重定向到新的多语言URI通常很有趣。如果将MULTILANG.migrate设置为TRUE，插件会自动为您完成。

示例

当迁移模式禁用时，/contact抛出404错误
当迁移模式启用时，/contact将执行301重定向到/en/contact（主要语言）

严格模式

当URL被重写时，如果检测到重复的URL，则会抛出错误。例如

[MULTILANG.rules.en]
contact = /contact
blog = /contact

这种行为称为“严格模式”，默认启用。

您可以通过将MULTILANG.strict设置为FALSE来禁用它，在这种情况下不会抛出错误。

透传模式

当开始一个新的单语项目时，保留对Multilang插件的依赖关系，同时不更改路由，以便有一天项目变成多语言。

passthru模式就是为了这种情况而设计的。将MULTILANG.passthru设置为TRUE以启用它。

当passthru模式启用时，插件不会做太多

它读取MULTILANG配置变量
它根据主要语言设置$f3->LANGUAGE
它不更改框架路由
它提供其通常的公共方法和属性

API

$ml = Multilang::instance();

current

返回当前URL检测到的语言

echo $ml->current;// ja

primary

返回主要语言名称

echo $ml->primary;// en

auto

如果语言已自动检测，则为TRUE

echo $ml->auto;//FALSE

passthru

如果passthru模式启用，则为TRUE

echo $ml->passthru;//FALSE

locale()

返回当前选定的区域设置

注意：如果MULTILANG.languages中配置的区域设置不在您的系统上，则此函数返回的值可能与您预期的不同。

echo $ml->locale();// en_GB.UTF-8

displayLanguage( $iso )

返回对应给定ISO代码的语言名称

注意：如果安装了intl扩展，名称将本地化，否则以英语返回。

// on a Danish route (with intl)
echo $ml->displayLanguage('fr');// fransk

// on a Russian route (with intl)
echo $ml->displayLanguage('fr');// французский

// on any route (without intl)
echo $ml->displayLanguage('fr');// French

displayCountry( $iso )

返回对应给定ISO代码的国家名称

注意：如果安装了intl扩展，名称将本地化，否则以英语返回。

// on a Danish route (with intl)
echo $ml->displayCountry('ru');// Rusland

// on a Russian route (with intl)
echo $ml->displayCountry('ru');// Россия

// on any route (without intl)
echo $ml->displayCountry('ru');// Russia

display( $iso )

displayLanguage( $iso )的别名[已弃用]

languages()

返回可用语言的列表

$ml->languages();// array('en','ja','es')

locales()

返回可用区域设置的列表（按语言索引）

$ml->locales();
/* array(
    'en' => 'en-GB,en-US,en',
    'ja' => 'ja-JP,ja',
    'es' => 'es-ES,es'
)*/

aliases()

返回所有别名的列表

（即使对于当前语言不可用）

$ml->aliases();// array('terms','blog','captcha')

isLocalized( $name, $lang=NULL )

检查路由是否在指定语言中本地化（默认为当前语言）

（本地化：既不是全局也不是排除的）

$ml->isLocalized('terms');// TRUE (current language)
$ml->isLocalized('terms','es');// TRUE
$ml->isLocalized('blog','es');// FALSE (excluded for Spanish)
$ml->isLocalized('captcha');// FALSE (global)
$ml->isLocalized('foo');// FALSE (non-existent route)

isGlobal( $name )

检查路由是否全局

$ml->isGlobal('captcha');// TRUE

alias( $name, $params=NULL, $lang=NULL )

从别名名称组装URL

此函数是$f3->alias()的语言感知版本。

echo $ml->alias('terms',NULL,'es');// /es/terminos-y-condiciones [local route]
echo $ml->alias('captcha');// /captcha [global route]

reroute( $url=NULL, $permanent=FALSE )

重定向到指定的URI

此函数是$f3->reroute()的语言感知版本。

如果您想在未命名的路由上自动添加语言前缀，请使用此函数。参见图重定向。

$ml->reroute('/en/contact'); // OK
$ml->reroute('/contact'); // OK => reroute to /xx/contact where xx is the current language

潜在改进

允许在域名级别进行识别（mydomain.jp/es或jp/es.mydomain.com）
如果F3核心实现了事件系统，则在"run"事件上设置钩子。核心。

xfra35 / f3-multilang

维护者

详细信息