@jahia/agentic 0.2.0 → 0.3.0

package/dist/windsurf/.windsurf/skills/jahia-content-translate-content/SKILL.md

@@ -1,273 +1,208 @@
 ---
 name: jahia-content-translate-content
-description: Adds language support to a Jahia site and translates existing content nodes. Use when asked to add a new language, fill in missing translations, or audit which content lacks i18n values.
+description: Adds site languages and translates existing Jahia content using MCP tools. Use when asked to enable a locale, fill in missing translations, or publish translated pages and content.
 ---
 
 # Skill: jahia-content-translate-content
 
-Adds languages to a Jahia site and populates i18n properties on existing content nodes via the GraphQL API.
+Translates existing content and manages multi-language support using MCP tools via the `jahia` MCP server.
+
+> **Never call Jahia's GraphQL API directly.** Use only MCP tools. If a capability is missing, report it — do not work around with curl/GraphQL.
 
 ---
 
 ## Prerequisites
 
-- Jahia running at `http://localhost:8080`
-- Credentials: `root` / `root1234` (default)
-- GraphQL endpoint: `http://localhost:8080/modules/graphql`
-
-**Always include both auth flags:**
-```bash
-curl -s -u root:root1234 \
-     -H "Content-Type: application/json" \
-     -H "Origin: http://localhost:8080" \
-     -X POST http://localhost:8080/modules/graphql \
-     -d '{"query": "..."}'
-```
-
-> ⚠️ The `Origin` header is **required** — omitting it returns `Permission denied`.
+- MCP server `jahia` connected with a valid API token
+- Know the target `siteKey` (call `site.list` if unsure)
+- Content already exists in a source locale
 
 ---
 
-## Step 1 — Enable the new language on the site
-
-Before creating or querying translations, the language must be declared on the site node.
-
-```bash
-# Check currently enabled languages
-curl -s -u root:root1234 \
-  -H "Content-Type: application/json" \
-  -H "Origin: http://localhost:8080" \
-  -X POST http://localhost:8080/modules/graphql \
-  -d '{
-    "query": "{ jcr { nodeByPath(path: \"/sites/mySite\") { properties(names: [\"j:languages\",\"j:defaultLanguage\"]) { name values } } } }"
-  }'
-
-# Add a language (e.g. "fr") — use setPropertiesBatch with the full new list
-curl -s -u root:root1234 \
-  -H "Content-Type: application/json" \
-  -H "Origin: http://localhost:8080" \
-  -X POST http://localhost:8080/modules/graphql \
-  -d '{
-    "query": "mutation { jcr { mutateNode(pathOrId: \"/sites/mySite\") { setPropertiesBatch(properties: [{name: \"j:languages\", values: [\"en\", \"fr\"]}]) { path } } } }"
-  }'
+## Step 1 — Check site languages
+
+```
+tool: site.get
+args: { "siteKey": "SITE_KEY" }
 ```
 
-> ⚠️ `j:languages` is a multi-valued property — always pass the **complete** list of languages, not just the new one. Passing only `["fr"]` would remove `"en"`.
+Check `languages` and `defaultLanguage`.
 
----
+- If the target locale is already present, continue.
+- If the target locale is missing, add it to the site first before writing translations.
 
-## Step 2 — Audit content missing translations
+---
 
-Query all i18n-bearing nodes and inspect which ones have empty values for the target language:
+## Step 2 — Read the source content
 
-```bash
-# Find all content nodes under /sites/mySite/contents
-curl -s -u root:root1234 \
-  -H "Content-Type: application/json" \
-  -H "Origin: http://localhost:8080" \
-  -X POST http://localhost:8080/modules/graphql \
-  -d '{
-    "query": "{ jcr { nodesByQuery(query: \"SELECT * FROM [jmix:i18n] WHERE ISDESCENDANTNODE(\u0027/sites/mySite/contents\u0027) ORDER BY [jcr:path] ASC\", queryLanguage: SQL2) { nodes { path primaryNodeType { name } properties(language: \"fr\") { name value } } } } }"
-  }'
+```
+tool: content.get
+args: {
+  "path": "/sites/SITE_KEY/home/about/main/intro-text",
+  "locale": "en"
+}
 ```
 
-Or query a specific content type:
+Note the properties that actually contain human-readable text.
 
-```bash
-curl -s -u root:root1234 \
-  -H "Content-Type: application/json" \
-  -H "Origin: http://localhost:8080" \
-  -X POST http://localhost:8080/modules/graphql \
-  -d '{
-    "query": "{ jcr { nodesByQuery(query: \"SELECT * FROM [namespace:article] WHERE ISDESCENDANTNODE(\u0027/sites/mySite/contents\u0027)\", queryLanguage: SQL2) { nodes { path properties(language: \"fr\") { name value } } } } }"
-  }'
-```
+To find a batch of nodes to translate:
 
-Look for nodes where i18n fields (`jcr:title`, `body`, etc.) have empty or null `value`.
+```
+tool: content.search
+args: {
+  "siteKey": "SITE_KEY",
+  "nodeType": "jmix:droppableContent",
+  "locale": "en",
+  "limit": 50
+}
+```
 
 ---
 
-## Step 3 — Set i18n properties
-
-### Single node
+## Step 3 — Identify which properties are i18n
 
-```bash
-curl -s -u root:root1234 \
-  -H "Content-Type: application/json" \
-  -H "Origin: http://localhost:8080" \
-  -X POST http://localhost:8080/modules/graphql \
-  -d '{
-    "query": "mutation { jcr { mutateNode(pathOrId: \"/sites/mySite/contents/articles/my-article\") { setPropertiesBatch(properties: [{name: \"jcr:title\", value: \"Mon article\", language: \"fr\"}, {name: \"body\", value: \"<p>Contenu ici</p>\", language: \"fr\"}]) { path } } } }"
-  }'
+```
+tool: content.type
+args: { "name": "jnt:bigText" }
 ```
 
-> ⚠️ Use `setPropertiesBatch` (plural), not `setProperty` (singular — does not exist in the Jahia GraphQL API).
+Translate only properties marked as internationalized.
 
-### Critical ordering rule
+Common i18n properties:
+- `jcr:title`
+- `text`
+- `body`
+- `description`
+- `subtitle`
 
-When a content type has **mandatory** i18n fields (other than `jcr:title`), set those **before** `jcr:title`. Setting `jcr:title` first can trigger a constraint check before all mandatory fields are present.
+Common non-i18n properties:
+- `j:view`
+- `j:templateName`
+- `jcr:primaryType`
+- references such as `j:node`
+- numeric or technical settings
 
-The safe pattern — set all mandatory i18n fields in a single `setPropertiesBatch` call:
+---
 
-```bash
-curl -s -u root:root1234 \
-  -H "Content-Type: application/json" \
-  -H "Origin: http://localhost:8080" \
-  -X POST http://localhost:8080/modules/graphql \
-  -d '{
-    "query": "mutation { jcr { mutateNode(pathOrId: \"/sites/mySite/contents/articles/my-article\") { setPropertiesBatch(properties: [{name: \"body\", value: \"<p>Contenu ici</p>\", language: \"fr\"}, {name: \"jcr:title\", value: \"Mon article\", language: \"fr\"}]) { path } } } }"
-  }'
-```
+## Step 4 — Write translated properties
 
----
+Use `content.update` with the target locale:
 
-## Step 4 — Bulk translation with Python
+```
+tool: content.update
+args: {
+  "path": "/sites/SITE_KEY/home/about/main/intro-text",
+  "locale": "fr",
+  "properties": {
+    "jcr:title": "À propos",
+    "text": "<p>Bienvenue sur notre site.</p>"
+  }
+}
+```
 
-For translating many nodes at once:
+Key rules:
+- Set all mandatory i18n properties in the same call.
+- Translate only i18n properties.
+- Preserve the HTML structure for rich text.
+- Do not translate technical choicelist values.
 
-```python
-import json
-from urllib.request import Request, urlopen
+---
 
-JAHIA = "http://localhost:8080"
-AUTH = ("root", "root1234")
+## Step 5 — Translate page titles
 
-import base64
-token = base64.b64encode(f"{AUTH[0]}:{AUTH[1]}".encode()).decode()
-HEADERS = {
-    "Content-Type": "application/json",
-    "Origin": JAHIA,
-    "Authorization": f"Basic {token}",
-}
+Page titles are also i18n:
 
-def gql(query):
-    body = json.dumps({"query": query}).encode()
-    req = Request(f"{JAHIA}/modules/graphql", data=body, headers=HEADERS, method="POST")
-    with urlopen(req) as r:
-        d = json.loads(r.read())
-    if "errors" in d:
-        print("ERR:", d["errors"][0]["message"][:120])
-    return d
-
-# 1. List all articles missing French title
-result = gql(
-    '{ jcr { nodesByQuery(query: "SELECT * FROM [namespace:article] '
-    "WHERE ISDESCENDANTNODE('/sites/mySite/contents') "
-    'ORDER BY [jcr:path] ASC", queryLanguage: SQL2) '
-    '{ nodes { path properties(language: "fr") { name value } } } } }'
-)
-
-nodes = result["data"]["jcr"]["nodesByQuery"]["nodes"]
-missing_fr = [
-    n["path"]
-    for n in nodes
-    if not any(p["name"] == "jcr:title" and p["value"] for p in n["properties"])
-]
-
-# 2. Set French translations (replace with actual translated values)
-translations = {
-    "/sites/mySite/contents/articles/article-1": ("Titre FR 1", "<p>Corps FR 1</p>"),
-    "/sites/mySite/contents/articles/article-2": ("Titre FR 2", "<p>Corps FR 2</p>"),
+```
+tool: content.update
+args: {
+  "path": "/sites/SITE_KEY/home/about",
+  "locale": "fr",
+  "properties": {
+    "jcr:title": "À propos"
+  }
 }
-
-for path, (title, body) in translations.items():
-    r = gql(
-        f'mutation {{ jcr {{ mutateNode(pathOrId: "{path}") {{'
-        f' setPropertiesBatch(properties: ['
-        f'  {{name: "body", value: {json.dumps(body)}, language: "fr"}},'
-        f'  {{name: "jcr:title", value: {json.dumps(title)}, language: "fr"}}'
-        f' ]) {{ path }} }} }} }}'
-    )
-    ok = "errors" not in r
-    print(f"  {'✓' if ok else '✗'} {path.split('/')[-1]}")
 ```
 
 ---
 
-## Step 5 — Choicelist fields and view-level translations
+## Step 6 — Verify translations
 
-### Choicelist fields should NOT be i18n
+Check the translated locale directly:
 
-If a CND property uses a choicelist (e.g. `category`, `status`), its stored values are language-agnostic keys like `"featured"` or `"draft"`. The display label is translated **in the view**, not in the JCR.
+```
+tool: content.get
+args: {
+  "path": "/sites/SITE_KEY/home/about/main/intro-text",
+  "locale": "fr"
+}
+```
 
-```tsx
-// In the view component — translate the stored key to a display label
-const STATUS_LABELS: Record<string, Record<string, string>> = {
-  en: { featured: "Featured", draft: "Draft" },
-  fr: { featured: "En vedette", draft: "Brouillon" },
-};
+Or search in the target locale:
 
-const lang = renderContext.getMainResourceLocale().getLanguage();
-const statusKey = properties.status as string;
-const statusLabel = STATUS_LABELS[lang]?.[statusKey] ?? statusKey;
+```
+tool: content.search
+args: {
+  "siteKey": "SITE_KEY",
+  "nodeType": "jmix:droppableContent",
+  "locale": "fr",
+  "limit": 20,
+  "projectProperties": ["jcr:title"]
+}
 ```
 
-Do **not** add `i18n` to the CND property for choicelists — the key should be the same in all languages.
-
-### Hardcoded UI strings
+---
 
-View-level strings that are not stored in JCR (button labels, headings, placeholder text) need locale-keyed label maps in the component:
+## Step 7 — Publish the translated locale
 
-```tsx
-const LABELS = {
-  en: { readMore: "Read more", by: "By" },
-  fr: { readMore: "Lire la suite", by: "Par" },
-};
+Publish the page or subtree in the target language:
 
-const t = LABELS[renderContext.getMainResourceLocale().getLanguage()] ?? LABELS.en;
-// Usage: <a>{t.readMore}</a>
 ```
-
----
-
-## Step 6 — Clean up orphaned translation nodes
-
-When you remove the `i18n` flag from a CND property (or delete a language from the site), orphaned `j:translation_XX` child nodes may remain. Inspect and remove them if needed:
-
-```bash
-# Find translation sub-nodes for a content node
-curl -s -u root:root1234 \
-  -H "Content-Type: application/json" \
-  -H "Origin: http://localhost:8080" \
-  -X POST http://localhost:8080/modules/graphql \
-  -d '{
-    "query": "{ jcr { nodeByPath(path: \"/sites/mySite/contents/articles/my-article\") { children { nodes { name primaryNodeType { name } } } } } }"
-  }'
-
-# Delete an orphaned translation node
-curl -s -u root:root1234 \
-  -H "Content-Type: application/json" \
-  -H "Origin: http://localhost:8080" \
-  -X POST http://localhost:8080/modules/graphql \
-  -d '{
-    "query": "mutation { jcr { deleteNode(pathOrId: \"/sites/mySite/contents/articles/my-article/j:translation_fr\") }"
-  }'
+tool: publication.publish
+args: {
+  "path": "/sites/SITE_KEY/home/about",
+  "languages": ["fr"]
+}
 ```
 
+If the translation touches both a page and child content, publish the page path so the subtree is included.
+
 ---
 
-## Step 7 — Publish translations
-
-After setting i18n properties, republish to make them live:
-
-```bash
-# Publish a single node for a specific language
-curl -s -u root:root1234 \
-  -H "Content-Type: application/json" \
-  -H "Origin: http://localhost:8080" \
-  -X POST http://localhost:8080/modules/graphql \
-  -d '{
-    "query": "mutation { jcr { mutateNode(pathOrId: \"/sites/mySite/contents/articles/my-article\") { publish(languages: [\"fr\"]) } } }"
-  }'
-
-# Publish all articles in both languages
-curl -s -u root:root1234 \
-  -H "Content-Type: application/json" \
-  -H "Origin: http://localhost:8080" \
-  -X POST http://localhost:8080/modules/graphql \
-  -d '{
-    "query": "mutation { jcr { mutateNodesByQuery(query: \"SELECT * FROM [namespace:article] WHERE ISDESCENDANTNODE(\u0027/sites/mySite/contents\u0027)\", queryLanguage: SQL2) { publish(languages: [\"en\", \"fr\"]) } } }"
-  }'
+## Common patterns
+
+### Translate all content under a page
+
+1. Discover the page structure:
+   ```
+   tool: page.structure
+   args: { "path": "/sites/SITE_KEY/home/about" }
+   ```
+2. Read each child node in the source locale:
+   ```
+   tool: content.get
+   args: { "path": "CHILD_PATH", "locale": "en" }
+   ```
+3. Write translated values to the target locale:
+   ```
+   tool: content.update
+   args: {
+     "path": "CHILD_PATH",
+     "locale": "fr",
+     "properties": { "jcr:title": "...", "text": "..." }
+   }
+   ```
+4. Publish the page in the new language.
+
+### Audit whether a page is publish-ready in the new locale
+
+```
+tool: publication.status
+args: {
+  "path": "/sites/SITE_KEY/home/about",
+  "language": "fr",
+  "subNodes": true,
+  "references": true
+}
 ```
 
 ---
@@ -276,22 +211,16 @@ curl -s -u root:root1234 \
 
 | Error | Cause | Fix |
 |-------|-------|-----|
-| `Permission denied` | Missing `Origin` header | Add `-H "Origin: http://localhost:8080"` |
-| i18n property returned empty after set | Missing `language:` in `properties()` query | Add `language: "fr"` to read call |
-| `ConstraintViolationException` on title set | Mandatory i18n field not set first | Use `setPropertiesBatch` with all mandatory fields in one call |
-| Language not appearing in site | `j:languages` mutation only had the new language | Pass the full list: `["en", "fr"]` |
-| Choicelist key changed per language | Property incorrectly declared `i18n` in CND | Remove `i18n` from the CND property; translate keys in the view |
+| `MANDATORY_PROPERTY_MISSING` | Not all required i18n properties were set | Set all mandatory translated properties in one `content.update` call |
+| Language not available | Locale not enabled on the site | Add the locale to the site first |
+| Properties appear empty | Wrong locale was used | Verify configured locales with `site.get` |
+| Translation not visible on the public site | It is still only in EDIT | Publish with `publication.publish` |
 
 ---
 
-## Workflow summary
+## Related skills
+
+- `/jahia-content-explore-structure` — find the right pages, nodes, and types first
+- `/jahia-content-publish` — publish translated content and inspect language-scoped status
+- `/jahia-content-create-content` — create new pages or content that will later need translation
 
-```
-1. Enable language   → mutateNode j:languages with full list
-2. Audit             → nodesByQuery with properties(language: "XX") to find gaps
-3. Translate         → setPropertiesBatch with language: "XX" for each i18n field
-4. View strings      → add locale-keyed label maps in .server.tsx
-5. Choicelists       → translate keys in the view, not the JCR
-6. Publish           → publish(languages: ["XX"]) for all affected nodes
-7. Verify            → query back with language: "XX" to confirm values
-```