README

轻松管理您的所有Laravel翻译字符串

• 翻译字符串到其他语言（DeepL，OpenAI或任何自定义服务）。
• 校对您的翻译字符串并自动修复语法和语法（OpenAI或任何自定义服务）。
• 查找所有区域设置中缺失的翻译字符串。
• 检测未使用的翻译键（代码库中未使用的键）。
• 排序您的翻译以自然顺序。

尝试Laratranslate - 一个强大的UI来管理所有翻译

安装

您可以通过Composer安装此包

composer require-dev elegantly/laravel-translator --dev

如果您不在生产中使用此包，请将以下行添加到您的.gitignore文件中

.translator.cache

接下来，使用以下命令发布配置文件

php artisan vendor:publish --tag="translator-config"

以下是发布配置文件的内容

return [

    /*
    |--------------------------------------------------------------------------
    | Language Paths
    |--------------------------------------------------------------------------
    |
    | This is the path where your translation files are stored. In a standard Laravel installation, you should not need to change it.
    |
    */
    'lang_path' => lang_path(),

    /*
    |--------------------------------------------------------------------------
    | Auto Sort Keys
    |--------------------------------------------------------------------------
    |
    | If set to true, all keys will be sorted automatically after any file manipulation such as 'edit', 'translate', or 'proofread'.
    |
    */
    'sort_keys' => false,

    /*
    |--------------------------------------------------------------------------
    | Third-Party Services
    |--------------------------------------------------------------------------
    |
    | Define the API keys for your third-party services. These keys are reused for both 'translate' and 'proofread'.
    | You can override this configuration and define specific service options, for example, in 'translate.services.openai.key'.
    |
    */
    'services' => [
        'openai' => [
            'key' => env('OPENAI_API_KEY'),
            'organization' => env('OPENAI_ORGANIZATION'),
            'request_timeout' => env('OPENAI_REQUEST_TIMEOUT'),
        ],
        'deepl' => [
            'key' => env('DEEPL_KEY'),
        ],
    ],

    /*
    |--------------------------------------------------------------------------
    | Translation Service
    |--------------------------------------------------------------------------
    |
    | These are the services that can be used to translate your strings from one locale to another.
    | You can customize their behavior here, or you can define your own service.
    |
    */
    'translate' => [
        /**
         * Supported: 'openai', 'deepl', 'MyOwnServiceClass::name'
         * Define your own service using the class's name: 'MyOwnServiceClass::class'
         */
        'service' => null,
        'services' => [
            'openai' => [
                'model' => 'gpt-4o',
                'prompt' => "
                            As an experienced copywriter and translator specializing in website copy, your task is to translate the provided content from a specific website.
                            Your translations should maintain the original tone while being adapted to the target language, ensuring they are both relevant and clear.
                            The content will be provided in JSON format, and you must translate it to the locale '{targetLocale}'.
                            Ensure that all JSON keys remain preserved and unchanged.
                            ",
            ],
        ],
    ],

    /*
    |--------------------------------------------------------------------------
    | Proofreading Service
    |--------------------------------------------------------------------------
    |
    | These are the services that can be used to proofread your strings.
    | You can customize their behavior here, or you can define your own service.
    |
    */
    'proofread' => [
        /**
         * Supported: 'openai', 'MyOwnServiceClass::name'
         * Define your own service using the class's name: 'MyOwnServiceClass::class'
         */
        'service' => null,
        'services' => [
            'openai' => [
                'model' => 'gpt-4o',
                'prompt' => '
                            Fix the grammar and syntax of the following JSON string while respecting the following rules:
                                - Never change the keys.
                                - Do not escape or modify HTML tags.
                                - Do not escape or modify special characters or emojis.
                                - Do not change the meaning or tone of the sentences.
                            ',
            ],
        ],
    ],

    /*
    |--------------------------------------------------------------------------
    | Search Code / Dead Code Service
    |--------------------------------------------------------------------------
    |
    | These are the services that can be used to detect dead translation strings in your codebase.
    | You can customize their behavior here, or you can define your own service.
    |
    */
    'searchcode' => [
        /**
         * Supported: 'php-parser', 'MyOwnServiceClass::name'
         */
        'service' => 'php-parser',

        /**
         * Files or directories to include in the dead code scan.
         */
        'paths' => [
            app_path(),
            resource_path(),
        ],

        /**
         * Files or directories to exclude from the dead code scan.
         */
        'excluded_paths' => [],

        /**
         * Translation keys to exclude from dead code detection.
         * By default, the default Laravel translations are excluded.
         */
        'ignored_translations' => [
            'auth',
            'pagination',
            'passwords',
            'validation',
        ],

        'services' => [
            'php-parser' => [
                /**
                 * To speed up detection, all the results of the scan will be stored in a file.
                 * Feel free to change the path if needed.
                 */
                'cache_path' => base_path('.translator.cache'),
            ],
        ],

    ],

];

自动翻译

在翻译任何内容之前，您必须选择并设置一个翻译服务。

此包默认包括两个服务

• OpenAI
• DeepL

但是，如果需要，您可以创建自己的服务。

设置OpenAI

首先，在配置文件中配置OpenAI密钥或定义环境变量

return [
    // ...

    'services' => [
        'openai' => [
            'key' => env('OPENAI_API_KEY'),
            'organization' => env('OPENAI_ORGANIZATION'),
            'request_timeout' => env('OPENAI_REQUEST_TIMEOUT'),
        ],
    ],

    // ...
]

设置DeepL

首先，在配置文件中配置DeepL密钥或定义环境变量

return [
    // ...

    'services' => [
        // ...
        'deepl' => [
            'key' => env('DEEPL_KEY'),
        ],
    ],

    // ...
]

从CLI

php artisan translator:translate

从代码

use Elegantly\Translator\Facades\Translator;

// Translate strings defined in PHP files
Translator::translateTranslations(
    source: 'fr',
    target: 'en',
    namespace: 'validation',
    keys: ['title', ...]
);

// Translate strings defined in JSON files
Translator::translateTranslations(
    source: 'fr',
    target: 'en',
    namespace: null,
    keys: ['title', ...]
);

校对翻译

此包允许您校对（即修复语法和语法）翻译字符串。

目前，此包包括一个服务

• OpenAI

但是，如果需要，您可以创建自己的服务。

设置OpenAI

首先，在配置文件中配置OpenAI密钥或定义环境变量

return [
    // ...

    'services' => [
        'openai' => [
            'key' => env('OPENAI_API_KEY'),
            'organization' => env('OPENAI_ORGANIZATION'),
            'request_timeout' => env('OPENAI_REQUEST_TIMEOUT'),
        ],
    ],

    // ...
]

从CLI

php artisan translator:proofread

从代码

use Elegantly\Translator\Facades\Translator;

// Proofread translation strings defined in PHP files
Translator::proofreadTranslations(
    locale: 'fr',
    namespace: 'auth',
    keys: ['title', ...]
);

// Proofread translation strings defined in JSON files
Translator::proofreadTranslations(
    locale: 'fr',
    namespace: null,
    keys: ['title', ...]
);

查找缺失的翻译

从CLI

php artisan translator:missing

从代码

// Compare /fr/validation.php and /en/validation.php
Translator::getMissingTranslations(
    source: 'fr',
    target: 'en',
    namespace: 'validation'
);

// Compare /fr.json and /en.json
Translator::getMissingTranslations(
    source: 'fr',
    target: 'en',
    namespace: null
);

查找未使用的翻译

重要

如果使用字符串插值，例如__("countries.{$user->country})，则死代码检测器无法检测翻译键。

配置代码扫描器

此包扫描整个代码库以查找未使用的翻译键。您可以根据需要自定义其行为

• 包含或排除特定路径。
• 排除翻译键。

定义要扫描的文件/目录

包含所有可能使用翻译键的路径。

支持.php和.blade.php文件。您可以在配置中自定义扫描的路径

return [
    // ...
    'searchcode' => [
        /**
         * Files or directories to include in the dead code scan.
         */
        'paths' => [
            app_path(), // Scan the entire /app directory
            resource_path(), // Scan the entire /resource directory
        ],
        // ...
    ]
    // ...
];

定义要排除扫描的文件/目录

为了优化或加快扫描速度，您可以排除某些路径。这对于

• 测试文件非常有用，这些文件不依赖于您的翻译文件。
• 与翻译无关的整个子目录。

提示

排除路径将加快扫描器。

忽略死代码检测器中的翻译键

有时，翻译字符串在代码库中没有使用，但您不想将其视为未使用。例如，您可能将所有国家名称存储在/countries.php中。

有时，当使用字符串插值时，例如__("countries.{$user->country})，扫描器可能无法检测到您的翻译字符串。

在这种情况下，您可以在配置中忽略翻译键

return [
    // ...
    'searchcode' => [
        // ...
        'ignored_translations' => [
            'countries', // Ignore all translation keys starting with 'countries'.
        ],
        // ...
    ]
    // ...
];

从CLI

php artisan translator:dead

从代码

// Compare /fr/validation.php and /en/validation.php
Translator::getDeadTranslations(
    locale: 'fr',
    namespace: 'validation'
);

// Compare /fr.json and /en.json
Translator::getDeadTranslations(
    locale: 'fr',
    namespace: null
);

排序和格式化翻译文件

从CLI

php artisan translator:sort

从代码

use Elegantly\Translator\Facades\Translator;

// Sort translations from `/fr/validation.php`
Translator::sortTranslations(
    locale: 'fr',
    namespace: 'validation'
);

// Sort translations from `/fr.json`
Translator::sortTranslations(
    locale: 'fr',
    namespace: null
);

测试

composer test

变更日志

请参阅CHANGELOG以获取有关最近更改的更多信息。

贡献

请参阅CONTRIBUTING以获取详细信息。

安全漏洞

请通过github或电子邮件向我报告任何安全漏洞。

致谢

• Quentin Gabriele
• 所有贡献者

许可

本软件包采用MIT许可协议。请参阅许可文件以获取更多详细信息。