x

LLM_MCP_GUIDE.md

@@ -163,6 +163,21 @@ Use one string only for URLs, slugs, IDs, and booleans/numbers as appropriate.
 6. Read back the page with `get_dynamic_page_detail`.
 7. If a section has auto-populated fields, trust the read-back result over the raw update payload.
 
+## Translating Page Builder Blocks
+
+Translate one language and one block at a time. This keeps the context compact and prevents a full payload replacement from overwriting existing languages.
+
+1. Call `get_page_translation_status` with `pageId` and the target `lang`.
+2. Pick one incomplete `sectionId`.
+3. Call `get_page_section_translation` with that `sectionId` and target `lang`. The default fallback supplies source text for untranslated fields and lists those fields in `fallbackPaths`.
+4. Translate the fields listed in `fallbackPaths`; preserve the payload's object and array shape.
+5. Call `update_section_translation` with `translations` and the `updatedAt` value as `expectedUpdatedAt`.
+6. Read the block again with `get_page_section_translation` and confirm `fallbackPaths` is empty.
+
+`update_section_translation` changes only the requested language in registered localized fields. It preserves other languages, URLs, IDs, layout configuration, and other non-translatable values. A `SECTION_VERSION_CONFLICT` response means the block changed after it was read; fetch it again before retrying.
+
+Use `get_page_section` with `lang=all` only when every stored language map is genuinely needed. A specific language returns resolved strings and uses fallback by default.
+
 ## What to Expect
 
 - `PRODUCT_CAROUSEL` may return products even when you did not send them.