{"id":22678288,"url":"https://github.com/hyperf-ext/translatable","last_synced_at":"2025-04-12T14:41:38.778Z","repository":{"id":56987685,"uuid":"295216802","full_name":"hyperf-ext/translatable","owner":"hyperf-ext","description":"The Hyperf Multilingual Model package.","archived":false,"fork":false,"pushed_at":"2021-07-30T18:00:08.000Z","size":26,"stargazers_count":4,"open_issues_count":0,"forks_count":2,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-04-11T17:25:10.838Z","etag":null,"topics":["database","hyperf","language","model","php","translation"],"latest_commit_sha":null,"homepage":"","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/hyperf-ext.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2020-09-13T18:54:28.000Z","updated_at":"2024-12-16T06:02:05.000Z","dependencies_parsed_at":"2022-08-21T12:50:24.992Z","dependency_job_id":null,"html_url":"https://github.com/hyperf-ext/translatable","commit_stats":null,"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hyperf-ext%2Ftranslatable","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hyperf-ext%2Ftranslatable/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hyperf-ext%2Ftranslatable/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hyperf-ext%2Ftranslatable/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hyperf-ext","download_url":"https://codeload.github.com/hyperf-ext/translatable/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248582816,"owners_count":21128455,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["database","hyperf","language","model","php","translation"],"created_at":"2024-12-09T18:14:41.378Z","updated_at":"2025-04-12T14:41:38.758Z","avatar_url":"https://github.com/hyperf-ext.png","language":"PHP","readme":"# Hyperf 多语言模型组件\n\n该组件为数据库模型提供实现多语言的能力。\n\n## 安装\n\n```shell script\ncomposer require hyperf-ext/translatable\n```\n\n## 发布配置\n\n```shell script\nphp bin/hyperf.php vendor:publish hyperf-ext/translatable\n```\n\n\u003e 文件位于 `config/autoload/translatable.php`。\n\n\u003e 注意，该组件依赖 `hyperf/translation`，不要忘记也要发布其配置并按需设置。\n\n## 配置\n\n```php\n[\n    /*\n    |--------------------------------------------------------------------------\n    | 应用语言列表\n    |--------------------------------------------------------------------------\n    |\n    | 包含应用所有可用语言的数组。\n    |\n    */\n    'locales' =\u003e [\n        'en',\n        'fr',\n        'zh' =\u003e [\n            'CN',\n            'TW',\n        ],\n    ],\n\n    /*\n    |--------------------------------------------------------------------------\n    | 语言分隔符\n    |--------------------------------------------------------------------------\n    |\n    | 用于在定义可用语言时连接语言和国家（或地区）之间的字符串。例如，如果设置为 `_`，\n    | 则“中文（中国）”的语言会以 `zh_CN` 的形式存储到数据库中。\n    |\n    */\n    'locale_separator' =\u003e '_',\n\n    /*\n    |--------------------------------------------------------------------------\n    | 默认语言\n    |--------------------------------------------------------------------------\n    |\n    | 指定要使用的默认语言。该组件默认使用 `hyperf/translation` 组件的语言设置。\n    | 如果出于某种原因想要覆盖此默认设置，则可以在此处设置要使用的默认值。\n    | 如果在此处设置一个值，它将仅使用当前的值，而不会回退到 `hyperf/translation`\n    | 组件的设置。\n    |\n    */\n    'locale' =\u003e null,\n\n    /*\n    |--------------------------------------------------------------------------\n    | 使用回退\n    |--------------------------------------------------------------------------\n    |\n    | 设置是否启用回退语言。为了增加灵活性，定义多语言模型的 $useTranslationFallback\n    | 属性可覆盖此处的设置。\n    |\n    */\n    'use_fallback' =\u003e false,\n\n    /*\n    |--------------------------------------------------------------------------\n    | 使用属性回退\n    |--------------------------------------------------------------------------\n    |\n    | 如果所选语言的属性为空，则属性回退特性将返回回退语言的翻译后的值。\n    | 注意，必须启用 `use_fallback`。\n    |\n     */\n    'use_property_fallback' =\u003e true,\n\n    /*\n    |--------------------------------------------------------------------------\n    | 回退语言\n    |--------------------------------------------------------------------------\n    |\n    | 回退语言是当请求的翻译不存在时，返回设置的回退语言的翻译。\n    | 如要禁用，请设置为 `false`。如果设置为 `null`，将会遍历语言列表中配置的所有语言，\n    | 直到找到第一个有效的翻译，否则会遍历完整个列表。\n    | 语言列表从上到下遍历，对于基于国家（或地区）的语言，会先检查简单的语言代码。\n    | 因此，例如在检查 `zh_CN` 之前会先检查 `zh`。\n    |\n    */\n    'fallback_locale' =\u003e 'en',\n\n    /*\n    |--------------------------------------------------------------------------\n    | Translation 模型命名空间\n    |--------------------------------------------------------------------------\n    |\n    | 定义默认的 'Translation` 类命名空间。\n    | 例如，如果要使用 `App\\Translations\\CountryTranslation` 而不是 `App\\CountryTranslation`，\n    | 请设置为 `App\\Translations`。\n    |\n    */\n    'translation_model_namespace' =\u003e null,\n\n    /*\n    |--------------------------------------------------------------------------\n    | Translation 模型后缀\n    |--------------------------------------------------------------------------\n    |\n    | 定义默认的 `Translation` 类名后缀。\n    | 例如，如果要使用 `CountryTrans` 而不是 `CountryTranslation`，请设置为 `Trans`。\n    |\n    */\n    'translation_suffix' =\u003e 'Translation',\n\n    /*\n    |--------------------------------------------------------------------------\n    | 语言字段名\n    |--------------------------------------------------------------------------\n    |\n    | 定义 `Translation` 模型的 'locale' 字段名。\n    |\n    */\n    'locale_key' =\u003e 'locale',\n\n    /*\n    |--------------------------------------------------------------------------\n    | 转换为数组时始终加载 Translation\n    |--------------------------------------------------------------------------\n    |\n    | 将其设置为 `false` 可以提升性能，但是在使用 `toArray()` 时不会返回翻译，\n    | 除非已经加载了关联的 `Translation` 模型。\n    |\n     */\n    'to_array_always_loads_translations' =\u003e true,\n\n    /*\n    |--------------------------------------------------------------------------\n    | 配置 RuleFactory 默认行为\n    |--------------------------------------------------------------------------\n    |\n    | 用于控制 RuleFactory 行为的默认值。\n    | 此处你可以为整个应用设置自己的默认格式和定界符。\n    |\n     */\n    'rule_factory' =\u003e [\n        'format' =\u003e \\HyperfExt\\Translatable\\Validation\\RuleFactory::FORMAT_ARRAY,\n        'prefix' =\u003e '%',\n        'suffix' =\u003e '%',\n    ],\n];\n```\n\n## 使用示例\n\n### 迁移\n\ncreate_posts_table.php\n```php\nuse Hyperf\\Database\\Schema\\Schema;\nuse Hyperf\\Database\\Schema\\Blueprint;\nuse Hyperf\\Database\\Migrations\\Migration;\n\nclass CreatePostsTable extends Migration\n{\n    public function up(): void\n    {\n        Schema::create('posts', function(Blueprint $table) {\n            $table-\u003eincrements('id');\n            $table-\u003estring('author');\n            $table-\u003etimestamps();\n        });\n    }\n\n    public function down(): void\n    {\n        Schema::dropIfExists('posts');\n    }\n}\n```\n\ncreate_post_translations_table\n```php\nuse Hyperf\\Database\\Schema\\Schema;\nuse Hyperf\\Database\\Schema\\Blueprint;\nuse Hyperf\\Database\\Migrations\\Migration;\n\nclass CreatePostTranslationsTable extends Migration\n{\n    public function up(): void\n    {\n        Schema::create('post_translations', function(Blueprint $table) {\n            $table-\u003eincrements('id');\n            $table-\u003einteger('post_id')-\u003eunsigned();\n            $table-\u003estring('locale')-\u003eindex();\n            $table-\u003estring('title');\n            $table-\u003etext('content');\n        \n            $table-\u003eunique(['post_id', 'locale']);\n            $table-\u003eforeign('post_id')-\u003ereferences('id')-\u003eon('posts')-\u003eonDelete('cascade');\n        });\n    }\n\n    public function down(): void\n    {\n        Schema::dropIfExists('post_translations');\n    }\n}\n```\n\n### 模型\n\nPost.php\n```php\nuse Hyperf\\Database\\Model\\Model;\nuse HyperfExt\\Translatable\\Contracts\\TranslatableInterface;\nuse HyperfExt\\Translatable\\Translatable;\n\nclass Post extends Model implements TranslatableInterface\n{\n    use Translatable;\n    \n    // 转换为数组时是否始终加载 Translation。默认为 `null`。\n    // 值为 `null` 时使用配置文件的 `to_array_always_loads_translations` 值。\n    protected static $autoloadTranslations = null;\n\n    // 删除记录的同时删除关联的翻译。默认为 `false`。\n    protected static $deleteTranslationsCascade = false;\n\n    // 配置该属性会覆盖配置文件的 `use_fallback` 值。\n    //protected $useTranslationFallback = false;\n\n    // 配置对应的 Translation 模型的多语言字段列表\n    public $translatedAttributes = ['title', 'content'];\n    \n    protected $fillable = ['author'];\n}\n```\n\nPostTranslation.php\n```php\nuse Hyperf\\Database\\Model\\Model;\n\nclass PostTranslation extends Model\n{\n    public $timestamps = false;\n    \n    // 多语言字段列表\n    protected $fillable = ['title', 'content'];\n}\n```\n\n### 获取已翻译的属性\n\n```php\nuse App\\Post;\nuse Hyperf\\Contract\\TranslatorInterface;\nuse Hyperf\\Utils\\ApplicationContext;\n\n$post = Post::query()-\u003efirst();\necho $post-\u003etranslate('en')-\u003etitle; // My first post\n\n$translator = ApplicationContext::getContainer()-\u003eget(TranslatorInterface::class);\n\n$translator-\u003esetLocale('en');\necho $post-\u003etitle; // My first post\n\n$translator-\u003essetLocale('de');\necho $post-\u003etitle; // Mein erster Post\n```\n\n### 存储已翻译的属性\n```php\nuse App\\Post;\n\n$post = Post::query()-\u003efirst();\necho $post-\u003etranslate('en')-\u003etitle; // My first post\n\n$post-\u003etranslate('en')-\u003etitle = 'My cool post';\n$post-\u003esave();\n\n$post = Post::query()-\u003efirst();\necho $post-\u003etranslate('en')-\u003etitle; // My cool post\n```\n\n### 填充翻译\n\n```php\nuse App\\Post;\n\n$data = [\n  'author' =\u003e 'Gummibeer',\n\n  'en' =\u003e ['title' =\u003e 'My first post'],\n  'fr' =\u003e ['title' =\u003e 'Mon premier post'],\n];\n$post = new Post();\n$post-\u003efill($data);\n$post-\u003esave();\n\necho $post-\u003etranslate('fr')-\u003etitle; // Mon premier post\n```","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhyperf-ext%2Ftranslatable","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhyperf-ext%2Ftranslatable","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhyperf-ext%2Ftranslatable/lists"}