P1 localization guide for agents

This page defines how an AI agent should help users create, review, and update localized content in P1. Agents should use plain product language in conversation and preserve P1’s content relationships and review controls underneath.

Use the right terminology

Use these terms in user-facing responses:

Core rules

• Use only locales configured for the site. Never invent or silently add a locale.
• Confirm the target locale when the request is ambiguous.
• Treat the Source and each Translation as related but independently reviewable content.
• Preserve intentional locale-specific differences such as currency, regulatory language, regional imagery, and market-specific calls to action.
• Do not overwrite locale-specific content merely because the Source changed.
• Use a branch or draft workflow for changes whenever the connected P1 tools support it.
• Show the user what will change before applying a destructive or broad update.
• Never publish or merge a translation without the required human approval.
• Report tool results accurately. Distinguish “drafted,” “saved,” “merged,” and “published.”

Decide which workflow applies

The user asks to translate an existing page

1. Identify the Source page and its source locale.
2. Identify the requested target locale.
3. Confirm the target locale is configured for the site.
4. Check whether a Translation already exists.
5. If no Translation exists, offer the available initialization choices:
   • Copy the Source content for in-editor translation.
   • Start with an empty page for a market-specific experience.
6. If a Translation exists, summarize the changes since the Translation’s last synchronized Source version.
7. Ask whether the user wants to translate, replace, mirror, or review the changes when more than one action is possible.
8. Apply the action on a branch or draft when supported.
9. Validate, preview, and request approval before merge or publish.

The user asks what changed

Use the locale comparison tools and answer in this order:

1. State the Source version and Translation version.
2. Give one plain-language summary, such as “7 changes since v10.”
3. List the meaningful content changes.
4. Identify any page structure change separately at the end.
5. Distinguish values that should follow the Source from values intentionally owned by the locale.
6. Recommend the smallest safe next action.

Do not expose raw diff classifications such as prop-drift or structural-gap unless the user is asking for technical details. When needed, explain them in plain language first.

The user asks to create locale-native content

1. Confirm the locale.
2. Confirm that the page should not be connected to a Source.
3. Use the requested template.
4. Create the page as locale-native content.
5. Do not describe it as a Translation or include it in Source synchronization workflows.

Action semantics

Use the product’s simplified action language when available:

Replace with Source

Use when the user wants the selected Translation value replaced with the current Source value. Before applying it:

• Identify the exact field or content block affected.
• Warn if the Translation value is intentionally locale-specific.
• Explain that the current localized value will be replaced.
• Apply only the selected change unless the user explicitly requests a broader replacement.

Translate with AI

Use when AI-assisted translation is available and the user requests it. The agent must:

• Generate a draft, not silently publish.
• Preserve links, variables, accessibility text, and structured content.
• Keep locale-specific values that are not linguistic content unless the user asks for adaptation.
• Present the result for human review.

If the action is unavailable, say so and offer to prepare translation-ready content instead.

Mirror into

Use when the user explicitly wants the Source content or structure copied into another locale. Confirm the destination locale and warn if an existing Translation will be overwritten or substantially changed.

Rollback change

Use only when the connected P1 workflow exposes rollback and the target change is unambiguous. Identify the change being reversed and confirm the resulting state. If rollback is unavailable, explain that the agent can prepare the inverse edit for review instead.

Use the localization tools

The locale-aware automation interface exposes two operations:

• list_locale_variants: Find a Source’s Translations and synchronization status.
• get_locale_diff: Compare a Translation with its Source and return classified changes.

The underlying API may use technical names such as canonical_document_id and canonical_synced_version. Keep those names in tool calls and developer logs, but translate them to Source and “changes since version N” in user-facing output.

A safe agent sequence is:

list_locale_variants
→ confirm source and target locale
→ get_locale_diff
→ summarize changes in plain language
→ ask for the intended action
→ apply edits on a branch or draft
→ validate and preview
→ request approval
→ merge or publish only when authorized

Example agent responses

Reviewing changes

The French translation has 7 changes since Source version 10. Five are text updates, one is a link update, and one is a page structure change. I can show the details, replace selected values with Source, or prepare a French translation for review.

Creating a translation

I found no German translation for this page. German is configured for the site. I can copy the Source content for translation or start an empty German page for a market-specific layout. Which approach should I use?

Protecting a regional override

The Source changed the promotion value, but the French page has a locale-specific promotion. I left the French value unchanged and marked the Source change for review.

Handling an unavailable action

AI translation is not available in this environment. I can still prepare the changed fields and preserve the existing page structure for a translator to review.

Do not do these things

• Do not translate into a locale that is not configured for the site.
• Do not assume that every Source change should overwrite the Translation.
• Do not flatten or rebuild page structure unless the user requests it.
• Do not claim that AI translation, rollback, merge, or publishing occurred without a successful tool result.