README

Bambolee翻译资源套件是Spatie的Laravel Translatable包的强大扩展，用于Laravel应用程序。它简化了API响应和动态JSON结构中翻译属性的处理，使开发多语言应用程序更加容易。

特性

与Spatie的Laravel Translatable无缝集成
动态处理JSON响应中的翻译属性
支持嵌套关系和深度翻译
可自定义嵌套翻译的递归深度
易于使用的Resource和Collection类用于API响应
兼容Laravel 8.x, 9.x, 10.x, 和 11.x

安装

您可以通过composer安装此包

composer require bambolee-digital/translatable-resource-kit

配置

安装后，发布配置文件

php artisan vendor:publish --provider="BamboleeDigital\TranslatableResourceKit\TranslatableResourceKitServiceProvider" --tag="config"

这将创建一个 config/translatable-resource-kit.php 文件，您可以在其中自定义包的行为。

您可以在配置文件中自定义中间件的行为

return [
    // disable debug 
    'debug' => false,
    // Disable automatic middleware registration
    'disable_middleware' => false,
    // Specify the middleware group (default is 'api')
    'middleware_group' => 'api',
    // ... other configurations
];

添加 set_locale

要将SetLocale中间件应用到您的API路由中，您可以将其添加到您的 routes/api.php 文件中。以下是如何操作的完整示例

use Illuminate\Support\Facades\Route;
use App\Http\Controllers\API\ProductController;
use App\Http\Controllers\API\CategoryController;

Route::middleware(['set_locale', SetLocale::class])->group(function () {
    // Product routes
    Route::prefix('products')->group(function () {
        Route::get('/', [ProductController::class, 'index']);
        Route::get('/{product}', [ProductController::class, 'show']);
        Route::post('/', [ProductController::class, 'store']);
        Route::put('/{product}', [ProductController::class, 'update']);
        Route::delete('/{product}', [ProductController::class, 'destroy']);
    });

    // Category routes
    Route::prefix('categories')->group(function () {
        Route::get('/', [CategoryController::class, 'index']);
        Route::get('/{category}', [CategoryController::class, 'show']);
        Route::post('/', [CategoryController::class, 'store']);
        Route::put('/{category}', [CategoryController::class, 'update']);
        Route::delete('/{category}', [CategoryController::class, 'destroy']);
    });

    // Add more route groups as needed
});

打开您的 routes/api.php 文件。
将中间件添加到您的API路由组中，如下所示

禁用中间件

如果您想禁用中间件的自动注册，请将配置文件中的 disable_middleware 选项设置为 true。

使用

1. 在您的模型中使用TranslatesAttributes特质

use BamboleeDigital\TranslatableResourceKit\Http\Traits\TranslatesAttributes;
use Spatie\Translatable\HasTranslations;

class Product extends Model
{
    use HasTranslations, TranslatesAttributes;

    public $translatable = ['name', 'description'];

    // ...
}

2. 为您的模型创建一个资源

use BamboleeDigital\TranslatableResourceKit\Http\Resources\TranslatableResource;

class ProductResource extends TranslatableResource
{
    // You can add custom logic here if needed
}

3. 为您的模型创建一个集合

use BamboleeDigital\TranslatableResourceKit\Http\Resources\TranslatableCollection;

class ProductCollection extends TranslatableCollection
{
    // You can add custom logic here if needed
}

4. 在控制器中使用

public function index()
{
    $products = Product::all();
    return new ProductCollection($products);
}

public function show(Product $product)
{
    return new ProductResource($product);
}

5. 使用中间件

中间件由包自动注册到配置中指定的组（默认为'api'）。您可以通过向API请求添加一个 lang 查询参数来设置区域设置，例如，?lang=pt 用于葡萄牙语。

如果您已禁用自动中间件注册，则可以使用以下方法之一手动注册它

在您的 app/Providers/AppServiceProvider.php 文件中

use Illuminate\Support\Facades\Route;
use BamboleeDigital\TranslatableResourceKit\Http\Middleware\SetLocale;

public function boot()
{
    Route::aliasMiddleware('set_locale', SetLocale::class);
    Route::pushMiddlewareToGroup('api', 'set_locale');
}

在您的 routes/api.php 文件中

use BamboleeDigital\TranslatableResourceKit\Http\Middleware\SetLocale;

Route::middleware([SetLocale::class])->group(function () {
    // Your API routes here
});

对于具有 app/Http/Kernel.php 的Laravel版本

protected $middlewareGroups = [
    'api' => [
        // ...
        \BamboleeDigital\TranslatableResourceKit\Middleware\SetLocale::class,
    ],
];

示例

以下是如何使用此包时JSON响应变化的示例

之前

{
  "id": 1,
  "name": {
    "en": "Laptop",
    "es": "Portátil",
    "pt": "Notebook"
  },
  "description": {
    "en": "Powerful laptop for professionals",
    "es": "Portátil potente para profesionales",
    "pt": "Notebook potente para profissionais"
  },
  "price": 999.99
}

之后（假设当前区域设置为'pt'，通过 ?lang=pt 设置）

{
  "id": 1,
  "name": "Notebook",
  "description": "Notebook potente para profissionais",
  "price": 999.99
}

如您所见，翻译字段自动解析为当前区域设置，简化了结构并使其在前端应用程序中更容易处理。

高级使用

自定义递归深度

您可以在 config/translatable-resource-kit.php 文件中自定义嵌套翻译的最大递归深度

return [
    'max_recursion_depth' => 3, // Default is 5
];

处理嵌套关系

TranslatesAttributes 特质自动处理嵌套关系。请确保您的模型中 $with 属性中的关系定义正确

class Product extends Model
{
    use HasTranslations, TranslatesAttributes;

    protected $with = ['category', 'tags'];

    // ...
}

自定义查询参数

如果您想使用不同的查询参数而不是 lang，则可以修改 SetLocale 中间件。您需要将中间件发布到您的应用程序

php artisan vendor:publish --provider="BamboleeDigital\TranslatableResourceKit\TranslatableResourceKitServiceProvider" --tag="middleware"

然后，编辑已发布的中间件文件 app/Http/Middleware/SetLocale.php 以更改查询参数名称。

变更日志

请参阅变更日志获取关于最近更改的更多信息。

贡献

请参阅贡献指南以获取详细信息。

安全

如果您发现任何安全相关的问题，请通过电子邮件security@bambolee.digital联系，而不是使用问题跟踪器。

鸣谢

许可证

MIT 许可证 (MIT)。请参阅许可证文件以获取更多信息。

bambolee-digital / translatable-resource-kit

维护者

详细信息