README

Muhawil 是一个 PHP 包，旨在简化加载和导出翻译的过程。名称 "muhawil" 来自阿拉伯语单词 مُحَوِّل，意为转换器或适配器，因为它可以方便地在多种格式中读取和写入翻译。

该包原生支持 6 种文件类型

JSON
MO（机器对象）
PHP
PO（可移植对象）
XLIFF（XML 本地化交换文件格式）
YAML

需求

PHP ^7.3|^8.0
ext-json PHP 扩展
ext-pcre PHP 扩展

安装

使用 Composer 安装该包

composer require alnaggar/muhawil

文件加载器

所有文件加载器都扩展了 Alnaggar\Muhawil\Loaders\FileLoader 抽象类，该类提供了一个 load (string $path) 方法，用于从指定路径的文件中加载翻译。

# Example of loading translations from a PHP file.

use Alnaggar\Muhawil\Loaders\PhpFileLoader;

$loader = new PhpFileLoader;

$translations = $loader->load('path/to/translations/file.php');

处理缺失值

当加载器遇到缺失的值，如为空或 null 时，默认使用翻译键本身作为值。这种做法确保缺失的翻译在 UI 中被显式标记以供更正。

要修改此行为，您可以利用 FileLoader 类的 setMissingValueCallback (callable $callback) 函数。该函数允许您传递一个回调函数，该函数接收两个参数：缺失翻译发生的文件路径和相应的翻译键。回调函数负责确定并返回适当的值。

# Example of logging missing translations for later review.

use Alnaggar\Muhawil\Loaders\PhpFileLoader;

$loader = new PhpFileLoader;

$callback = function (string $path, string $key){
  $message = "Found an untranslated key: {$key} while loading the translations at {$path}";
  error_log($message);

  return $key;
};

$loader->setMissingValueCallback($callback);

$translations = $loader->load('path/to/translations/file.php');

文件导出器

所有文件导出器都扩展了 Alnaggar\Muhawil\Dumpers\FileDumper 抽象类，该类提供了一个 dump (array $translations, string $path, array $arguments []) 方法，用于将翻译导出到指定路径的文件中，如果需要，使用传递的参数。

// Example of dumping translations into a PHP file.

use Alnaggar\Muhawil\Dumpers\PhpFileDumper;

$translations = [
    'welcome' => 'Welcome to our website!',
    'farewell' => 'Wishing you success on your new journey. Farewell!'
];

$dumper = new PhpFileDumper;

$dumper->dump($translations, 'path/to/translations/file.php');

JSON

使用 Alnaggar\Muhawil\Loaders\JsonFileLoader 类加载 JSON 翻译。

使用 Alnaggar\Muhawil\Dumpers\JsonFileDumper 类导出 JSON 翻译，可选的 flags 参数将传递给 json_encode 函数。

// Example of dumping translations into a JSON file.

use Alnaggar\Muhawil\Dumpers\JsonFileDumper;

$translations = [
    'welcome' => 'Welcome to our website!',
    'farewell' => 'Wishing you success on your new journey. Farewell!'
];

$dumper = new JsonFileDumper;

$dumper->dump($translations, 'path/to/translations/file.json', ['flags' => JSON_PRETTY_PRINT | JSON_INVALID_UTF8_IGNORE]);

MO

使用 Alnaggar\Muhawil\Loaders\MoFileLoader 类加载 MO 翻译。

使用 Alnaggar\Muhawil\Dumpers\MoFileDumper 类导出 MO 翻译，可选的 metadata 参数可以包含 MO 文件中的信息，如 Language 和 Plural-Forms。

// Example of dumping translations into an MO file.

use Alnaggar\Muhawil\Dumpers\MoFileDumper;

$translations = [
    'welcome' => 'Welcome to our website!',
    'farewell' => 'Wishing you success on your new journey. Farewell!'
];

$dumper = new MoFileDumper;

$dumper->dump($translations, 'path/to/translations/file.mo', [
    'Language' => 'ar'
    'Plural-Forms' => 'nplurals=6; plural=n==0 ? 0 : n==1 ? 1 : n==2 ? 2 : n % 100 >= 3 && n % 100 <= 10 ? 3 : n % 100 >= 11 ? 4 : 5;'
]);

PHP

使用 Alnaggar\Muhawil\Loaders\PhpFileLoader 类加载 PHP 翻译。

使用 Alnaggar\Muhawil\Dumpers\PhpFileDumper 类导出 PHP 翻译。

PO

使用 Alnaggar\Muhawil\Loaders\PoFileLoader 类加载 PO 翻译。

使用 Alnaggar\Muhawil\Dumpers\PoFileDumper 类导出 PO 翻译，可选的 metadata 参数可以包含 PO 文件头部的信息，如 Language 和 Plural-Forms。

// Example of dumping translations into a PO file.

use Alnaggar\Muhawil\Dumpers\PoFileDumper;

$translations = [
    'welcome' => 'Welcome to our website!',
    'farewell' => 'Wishing you success on your new journey. Farewell!'
];

$dumper = new PoFileDumper;

$dumper->dump($translations, 'path/to/translations/file.po', [
    'Language' => 'ar'
    'Plural-Forms' => 'nplurals=6; plural=n==0 ? 0 : n==1 ? 1 : n==2 ? 2 : n % 100 >= 3 && n % 100 <= 10 ? 3 : n % 100 >= 11 ? 4 : 5;'
]);

XLIFF

使用 Alnaggar\Muhawil\Loaders\XliffFileLoader 类加载 XLIFF 翻译。

使用 Alnaggar\Muhawil\Dumpers\XliffFileDumper 类导出 XLIFF 翻译，需要两个参数：source_locale 和 target_locale。还有一个可选参数 legacy，如果设置为 true，则将翻译导出到 XLIFF 1.2 格式而不是默认的 2.0 格式。

// Example of dumping translations into an XLIFF file.

use Alnaggar\Muhawil\Dumpers\XliffFileDumper;

$translations = [
    'welcome' => 'Welcome to our website!',
    'farewell' => 'Wishing you success on your new journey. Farewell!'
];

$dumper = new XliffFileDumper;

$dumper->dump($translations, 'path/to/translations/file.xliff', [
  'source_locale' => 'en', 
  'target_locale' => 'ar', 
  'legacy' => true
]);

注意

如果 legacy 设置为 false（默认值），还有一个额外的可选参数 file_id，可以用作 XLIFF 2.0 版本中 file 节点的 id 属性值。

YAML

使用 Alnaggar\Muhawil\Loaders\YamlFileLoader 类加载 YAML 翻译。

使用 Alnaggar\Muhawil\Dumpers\YamlFileDumper 类导出 YAML 翻译，可选的 dry 参数用于确定和生成相似映射的锚点和别名。

// Example of dumping translations into a YAML file.

use Alnaggar\Muhawil\Dumpers\YamlFileDumper;

$translations = [
    'welcome_message' => 'Welcome to our application!',
    'greeting' => 'Hello, world!',
    'farewell' => 'Goodbye, see you soon!',
    'errors' => [
      'not_found' => 'The requested resource was not found.',
      'internal_error' => 'An internal server error occurred. Please try again later.'
    ],
    'common_actions' => [
      'save' => 'Save',
      'cancel' => 'Cancel',
      'delete' => 'Delete'
    ],
    'user' => [
      'profile' => 'Profile',
      'settings' => 'Settings',
      'logout' => 'Logout',
      'actions' => [
        'create' => 'Create',
        'save' => 'Save',
        'cancel' => 'Cancel',
        'delete' => 'Delete'
      ]
    ]
];

$dumper = new YamlFileDumper;

$dumper->dump($translations, 'path/to/translations/file.yaml', ['dry' => true]);

YAML 加载器和导出器仅支持简单的 YAML 结构，包括映射、嵌套映射和标量值。所有键和标量值都可以使用双引号、单引号或不加引号，不允许使用特殊的 YAML 字符。

自定义加载器和导出器

您可以通过实现 Alnaggar\Muhawil\Interfaces\Loader 和 Alnaggar\Muhawil\Interfaces\Dumper 接口及其相应的 load 和 dump 方法，为任何类型的存储（如数据库或其他存储）实现自己的加载器和导出器。

例如，要创建一个数据库的自定义加载器，您需要创建一个实现 Loader 接口的类，并定义 load 方法以从数据库中检索翻译。类似地，对于自定义导出器，实现 Dumper 接口并定义 dump 方法以将翻译保存回数据库。

这种灵活性允许您根据需要定制 Muhawil，而不仅仅是提供的基于文件的加载器和导出器。

贡献

如果您发现任何问题或对改进有建议，请随时在 GitHub 仓库中提交问题或拉取请求。

鸣谢

由 Safouene1 设计的巴勒斯坦横幅和徽章。

许可证

Muhawil 是开源软件，采用 MIT 许可证。

alnaggar / muhawil

维护者

详细信息