跳至主要内容
版本：5.1

步骤 4 添加语言支持

简介​

到目前为止，我们模块中关联的任何文本都为英文。在此步骤中，我们将对其进行更改，使其能够显示多种语言，以便

  • 管理员可以以其首选语言查看模块描述
  • 网站访问者可以看到模块输出，其中“Hello”被替换为他们自己的语言中的问候语

要在您的网站上查看多种语言，您必须将其配置为多语言。您可以在网上找到各种视频和教程，例如此教程。

在此步骤中，我们编写了支持多种语言的基础架构，但仅实现了英语。如果您将自己的网站配置为多语言，则可以轻松扩展此处的内容以实现另一种语言。

源代码可在mod_hello 步骤 4找到。

语言文件​

我们的 mod_hello 模块有 3 个输出文本的位置

  1. 在清单文件的<name>元素中设置的模块名称。
  2. 在清单字段的<description>元素中设置的模块描述
  3. 模块在网站页面上输出的问候语“Hello”。

我们为这些文本字符串定义了 3 个语言常量：MOD_HELLO_NAME、MOD_HELLO_DESCRIPTION 和 MOD_HELLO_GREETING。

所有语言常量都应以扩展名（唯一）开头，因为这可以确保不会与其他扩展名冲突。按照惯例，这些都大写。

我们在 2 个语言文件中定义了这些常量的值

mod_hello/language/en-GB/mod_hello.sys.ini
; mod_hello language strings for administrator listings of modules
MOD_HELLO_NAME="Joomla Module Tutorial"
MOD_HELLO_DESCRIPTION="Source code for the Joomla module tutorial"
mod_hello/language/en-GB/mod_hello.ini
; language strings used inside mod_hello 
MOD_HELLO_NAME="Joomla Module Tutorial"
MOD_HELLO_DESCRIPTION="Source code for the Joomla module tutorial"
MOD_HELLO_GREETING="Hello "

.sys.ini 文件用于文本出现在列出多个模块的 HTML 表单中的常量。例如，在管理员后端“系统/管理/扩展”中，扩展列表具有

  • “名称”字段中的扩展名（如清单文件<name>元素中所定义）
  • 扩展描述，作为扩展名的工具提示（如清单文件<description>元素中所定义）。

.ini 文件用于显示单个模块时出现的常量。

.ini 文件中也需要名称和描述常量，因为当管理员选择“内容/网站模块”并创建或编辑 mod_hello 模块时，Joomla 会显示它们。在这种情况下，Joomla 只读取 .ini 文件，因为它是要显示的单个 mod_hello 模块。

拆分的原因是性能，以最大限度地减少必须读取的语言常量的数量。

更新的清单文件​

我们用语言常量替换清单文件中的英文文本，并且我们还告诉 Joomla 安装程序在哪里可以找到语言文件

如清单文件语言部分所述，有两种方法可以在扩展中包含语言文件，我们选择第二种方法。

mod_hello/mod_hello.xml
<?xml version="1.0" encoding="UTF-8"?>
<extension type="module" client="site" method="upgrade">
    <name>MOD_HELLO_NAME</name>
    <version>1.0.4</version>
    <author>me</author>
    <creationDate>today</creationDate>
    <description>MOD_HELLO_DESCRIPTION</description>
    <namespace path="src">My\Module\Hello</namespace>
    <files>
        <folder module="mod_hello">services</folder>
        <folder>src</folder>
        <folder>tmpl</folder>
        <folder>language</folder>
    </files>
</extension>

解释语言常量​

为了获取与语言常量关联的文本，源代码需要执行 2 件事

  1. 加载相应的语言文件（.ini 或 .sys.ini）
  2. 获取与单个语言常量关联的文本。

我们可以在模块中使用以下方法加载语言 .ini 文件

use Joomla\CMS\Factory;

$language = Factory::getApplication()->getLanguage();
$language->load('mod_hello', JPATH_BASE . '/modules/mod_hello');

我们使用以下方法获取与单个语言常量关联的文本

use Joomla\CMS\Language\Text;
...
$text = Text::_('MOD_HELLO_GREETING');

不要担心函数名称是下划线 - 它只是一个普通的 PHP 函数。

我们将在分派器代码中添加这些行。

在管理员表单中，Joomla 会负责加载语言和解释语言常量，例如通过“内容/网站模块”编辑模块时。

我们更新后的主分派器源代码文件现在是

mod_hello/src/Dispatcher/Dispatcher.php
<?php

namespace My\Module\Hello\Site\Dispatcher;

\defined('_JEXEC') or die;

use Joomla\CMS\Dispatcher\DispatcherInterface;
use Joomla\CMS\Helper\ModuleHelper;
use Joomla\CMS\Factory;
use Joomla\CMS\Language\Text;
use My\Module\Hello\Site\Helper\HelloHelper;

class Dispatcher implements DispatcherInterface
{
    public function dispatch()
    {
        $language = Factory::getApplication()->getLanguage();
        $language->load('mod_hello', JPATH_BASE . '/modules/mod_hello');
        
        $username = HelloHelper::getLoggedonUsername('Guest');

        $hello = Text::_('MOD_HELLO_GREETING') . $username;

        require ModuleHelper::getLayoutPath('mod_hello');
    }
}

安装、提示和故障排除​

再次，压缩您的 mod_hello 目录并在 Joomla 上安装升级后的模块。

.sys.ini 中语言字符串的文本与之前的步骤略有不同，因此当扩展安装后以及导航到“管理员/系统/管理/扩展”时，您应该能够看到这些差异。

模块输出应相同。

一个有用的提示是转到“系统/全局配置/系统”选项卡，然后将“调试语言”设置为“是”，然后“保存”。

这会导致语言字符串以两个星号之间突出显示。通过切换出现的“语言显示”选项，您可以让 Joomla 输出语言常量或关联文本。

如果您正在编写一个包含大量语言常量且支持多种语言的模块，那么您应该考虑如何最好地在语言文件中对它们进行排序，否则在外国语言文件中可能难以发现缺少的常量。例如，在 Joomla 扩展中，它们按字母顺序排序。