added translation

API.md

@@ -3,6 +3,8 @@
 Endpoint reference for the Marketplace Backoffice.  
 Base URL: `https://your-api-domain.com/api`
 
+> 🇷🇺 Документация на русском языке: [API.ru.md](./API.ru.md)
+
 ---
 
 ## Projects
@@ -237,6 +239,16 @@ Response 200:
         { "key": "Storage", "value": "256GB" }
       ],
       "subcategoryId": "sub1",
+      "translations": {
+        "ru": {
+          "name": "iPhone 15 Про",
+          "simpleDescription": "Последний iPhone...",
+          "description": [
+            { "key": "Цвет", "value": "Чёрный" },
+            { "key": "Память", "value": "256 ГБ" }
+          ]
+        }
+      },
       "comments": [
         {
           "id": "c1",
@@ -280,7 +292,16 @@ Body:
   "simpleDescription": "Short description",
   "description": [
     { "key": "Size", "value": "Large" }
-  ]
+  ],
+  "translations": {                    // optional - localized content for marketplace
+    "ru": {
+      "name": "Новый товар",
+      "simpleDescription": "Краткое описание",
+      "description": [
+        { "key": "Размер", "value": "Большой" }
+      ]
+    }
+  }
 }
 
 Response 201: (created item object)
@@ -369,6 +390,7 @@ Response 201:
 - `badges`: optional string array. Predefined values with UI colors: `new`, `sale`, `exclusive`, `hot`, `limited`, `bestseller`, `featured`. Custom strings are also allowed.
 - `imgs`: always send the **complete** array on update, not individual images.
 - `description`: array of `{ key, value }` pairs - free-form attributes per item.
+- `translations`: optional object keyed by language code (`"ru"`, `"en"`, etc.) — each value may contain `name`, `simpleDescription`, `description[]`. The marketplace frontend should use these when rendering in the corresponding language, falling back to the default fields if a translation is absent.
 - Auto-save from the backoffice fires `PATCH` with a single field every ~500 ms.
 
 ---
@@ -423,3 +445,60 @@ The `id` field on subcategories is editable via `PATCH` to allow renaming slugs.
 | Category | all subcategories (recursive) and their items |
 | Subcategory | all nested subcategories (recursive) and their items |
 | Item | nothing else |
+
+---
+
+## Internationalization (i18n)
+
+The API supports localized content for items and categories via the `translations` field.
+
+### `translations` object structure
+
+Any entity that supports translations accepts the same nested shape:
+
+```json
+{
+  "translations": {
+    "ru": {
+      "name": "Название",
+      "simpleDescription": "Краткое описание",
+      "description": [
+        { "key": "Цвет", "value": "Чёрный" }
+      ]
+    }
+  }
+}
+```
+
+- Keys are ISO 639-1 language codes (`"ru"`, `"en"`, etc.).
+- All sub-fields are optional — omit what you don't need.
+- Currently supported in the backoffice: `ru` (Russian).
+
+### Requesting a Specific Language
+
+Pass `?lang=ru` to any GET endpoint. The backend will:
+
+1. Return the default top-level fields as-is.
+2. Merge the matching `translations[lang]` values into the response, overwriting the default fields.
+3. Fall back gracefully to the default language if no translation exists for the requested lang.
+
+```
+GET /api/items/:itemId?lang=ru
+GET /api/subcategories/:subcategoryId/items?lang=ru
+```
+
+Alternatively, you can use the `Accept-Language` header:
+
+```
+Accept-Language: ru
+```
+
+### Fallback Behaviour
+
+| Scenario | Returned value |
+|---|---|
+| Translation exists for requested lang | Translated value |
+| Translation missing for requested lang | Default (base) field value |
+| `lang` param omitted | Default (base) field value |
+
+> 🇷🇺 See [API.ru.md](./API.ru.md) for full documentation in Russian.