Add localization system

Author: tobyzerner

CHANGELOG.md

@@ -13,9 +13,17 @@ and this project adheres to
 - Replace `Resource::getId(object $model, Context $context): string` method with
   `Resource::id(): Id` method, which returns an `Id` field instance to define ID
   schema, validation, and writability
+- Custom deserializers on `ToOne` relationships now receive the resolved model
+  rather than the raw relationship object, for consistency with `ToMany`
 
 ### Added
 
+- Add localization system for customizable error messages
+    - Add `JsonApi::messages()` method for merging custom error messages with
+      defaults
+    - Add `JsonApi::setTranslator()` method for providing custom translator
+      implementations
+    - Add `Context::translate()` method for accessing the translation system
 - Add `Id` field class for customizing resource ID behavior, including type
   constraints, client-generated IDs via `writableOnCreate()`, and validation
 - Add `linkageMeta()` method to relationship fields for adding meta to resource
@@ -26,6 +34,7 @@ and this project adheres to
 
 ### Changed
 
+- Error messages now use the localization system
 - Various performance optimizations to improve serialization speed
 - Improve OpenAPI schema generation to properly handle ID field constraints and
   avoid redundant properties

README.md

@@ -22,6 +22,7 @@ support for:
 - **Deleting** resources (`DELETE /articles/1`)
 - **Content negotiation**
 - **Error handling**
+- **Localization** for customizing error messages
 - **Extensions** including Atomic Operations
 - **Generating OpenAPI definitions**
 

docs/.vitepress/config.ts

@@ -51,6 +51,7 @@ export default defineConfig({
                         text: 'Heterogeneous Collections',
                         link: '/collections',
                     },
+                    { text: 'Localization', link: '/localization' },
                     { text: 'OpenAPI Definitions', link: '/openapi' },
                 ],
             },

docs/context.md

@@ -56,6 +56,9 @@ class Context
     // Get the value of a query param
     public function queryParam(string $name, $default = null): mixed;
 
+    // Translate a message using the API's translator
+    public function translate(string $key, array $replacements = []): string;
+
     // Get the parsed JSON:API payload
     public function body(): ?array;
 

docs/errors.md

@@ -49,3 +49,9 @@ class ImATeapotException implements ErrorProvider
 
 Exceptions that do not implement this interface will result in a generic
 `500 Internal Server Error` response.
+
+## Customizing Error Messages
+
+Many of the built-in error messages can be customized using the
+[localization system](localization.md). This allows you to provide localized or
+custom error messages throughout your API.

docs/index.md

@@ -21,6 +21,7 @@ support for:
 - **Relationship** URLs (`/articles/1/relationships/author`)
 - **Content negotiation**
 - **Error handling**
+- **Localization** for customizing error messages
 - **Extensions** including Atomic Operations
 - **Generating OpenAPI definitions**
 

docs/localization.md

@@ -0,0 +1,70 @@
+# Localization
+
+json-api-server includes a basic localization system that allows you to
+customize error messages in your API responses.
+
+## Default Language
+
+By default, the server uses English for all error messages. These are defined in
+the `Tobyz\JsonApi\Translation\EnglishCatalogue` class.
+
+## Customizing Messages
+
+You can customize messages in two ways:
+
+### Merging Custom Messages
+
+To override specific messages while keeping the defaults:
+
+```php
+$api = new JsonApi();
+
+$api->messages([
+    'resource.not_found' => 'The requested resource could not be found',
+    'pagination.size_exceeded' => 'The requested page size is too large',
+]);
+```
+
+This will merge your custom messages with the default English messages.
+
+### Using a Custom Translator
+
+For complete control over localization, you can provide your own translator
+implementation:
+
+```php
+use Tobyz\JsonApiServer\Translation\TranslatorInterface;
+
+class CustomTranslator implements TranslatorInterface
+{
+    public function translate(string $key, array $replacements = []): string
+    {
+        // Your custom translation logic here
+        return $translation;
+    }
+}
+
+$api = new JsonApi();
+$api->setTranslator(new CustomTranslator());
+```
+
+## Message Keys
+
+Messages support placeholder replacements using the `:placeholder` syntax. The
+replacement values are passed as an array:
+
+```php
+$context->translate('resource.not_found', ['identifier' => 'users']);
+// Results in: "Resource not found: users"
+```
+
+## Using Localization in Custom Code
+
+You can access the localization system in your custom code through the Context
+object:
+
+```php
+use Tobyz\JsonApiServer\Context;
+
+$message = $context->translate('custom.key', ['name' => 'value']);
+```

src/Context.php

@@ -49,6 +49,11 @@ public function __construct(public JsonApi $api, public ServerRequestInterface $
         $this->resourceMeta = new WeakMap();
     }
 
+    public function translate(string $key, array $replacements = []): string
+    {
+        return $this->api->translator->translate($key, $replacements);
+    }
+
     /**
      * Get the value of a query param.
      */
@@ -150,7 +155,7 @@ public function sparseFields(Resource $resource): array
 
             if (!is_string($requested)) {
                 throw (new BadRequestException(
-                    'Sparse fieldsets must be comma-separated strings.',
+                    $this->translate('request.fields_invalid'),
                 ))->setSource(['parameter' => "fields[$type]"]);
             }
 

src/Endpoint/Concerns/FindsResources.php

@@ -25,7 +25,13 @@ private function findResource(Context $context, string $id)
         }
 
         if (!($model = $collection->find($id, $context))) {
-            throw new ResourceNotFoundException($collection->name(), $id);
+            throw new ResourceNotFoundException(
+                $collection->name(),
+                $id,
+                $context->translate('resource.not_found', [
+                    'identifier' => $collection->name() . '.' . $id,
+                ]),
+            );
         }
 
         return $model;

src/Endpoint/Concerns/IncludesData.php

@@ -87,9 +87,9 @@ private function validateInclude(
                 continue 2;
             }
 
-            throw (new BadRequestException("Invalid include [$path$name]"))->setSource([
-                'parameter' => 'include',
-            ]);
+            throw (new BadRequestException(
+                $context->translate('request.include_invalid', ['include' => $path . $name]),
+            ))->setSource(['parameter' => 'include']);
         }
     }