Ad Image Localization Codex Plugin

Localize image creatives with Codex built-in image generation. No extra image API required.

中文说明 · Installation · Skill · License

Ad Image Localization is a Codex plugin that packages the ad-image-localization skill, helper scripts, examples, and QA workflow for turning source image creatives into localized, platform-ready ad and social assets. It is designed for marketers, UA teams, ecommerce operators, and creators who need multilingual creative variants without setting up a separate image-generation API.

Version 0.3 adds a job preflight, ratio-based delivery profiles, provenance-aware manifests, and a recorded visual-QA release gate.

Why This Skill

• Uses your Codex subscription quota for image generation and editing.
• No extra API setup: no image API key, no separate billing account, no external generation service required.
• Native visual output: relies on Codex built-in vision, image generation, and image editing instead of simple masking or mechanical text replacement.
• Imagegen-first workflow: pixel-changing work should invoke Codex's imagegen skill and built-in image_gen path first; local scripts are only for deterministic finishing steps.
• Campaign-ready workflow: standardized filenames, manifests, common ad sizes, visual QA, and Culture-Aware QA before delivery.
• Good long-running value: slower than a dedicated batch API, but low setup cost and strong output quality make it useful for marketing teams that can let jobs run in the background.

Tradeoff

The built-in Codex image workflow is slower than purpose-built bulk image APIs. This skill is optimized for convenience, native visual quality, and low setup cost rather than maximum throughput.

Future work may include a separate high-throughput skill based on the Nano Banana API for faster batch production.

What It Does

• Translates visible text inside images into target languages.
• Uses strict RTL-aware localization by default for Arabic and other RTL languages, with copy-only fallback only when QA finds the true RTL layout weaker.
• Preserves brand names, product names, logos, subjects, and visual hierarchy.
• Adapts creatives into common ad/social sizes:
  • 1200x1200
  • 1920x1080
  • 1080x1350
  • 1080x1920
  • 1200x628
• Generates standard ad ratios with imagegen; handles special close-ratio resolutions by cover-cropping only from safe model-generated outputs.
• Preflights every job into unique generations and deterministic derivatives, preventing duplicate model calls for the same aspect ratio.
• Maintains brand/product terminology memory.
• Produces clean upload-ready filenames and provenance-aware manifests.
• Runs visual QA before delivery, with one regeneration pass for failed outputs.
• Runs Culture-Aware QA during QA and moves potentially sensitive outputs into Flagged by Culture-Aware QA/ for user review.
• Includes deterministic tooling for job planning, same-ratio normalization, safe derivative crops, manifests, recorded visual QA, release checks, contact sheets, culture-aware flags, and terminology memory.

Output Folder Structure

Each task should live in its own run folder. Keep the workspace root clean and avoid mixing source images, raw model outputs, scripts, QA files, zips, and final deliverables in one flat folder.

ad-localization-runs/
└── rabbit-social-networks_20260623_1430/
    ├── source/
    ├── final/
    ├── qa/
    │   ├── preflight.json
    │   ├── manifest.json
    │   ├── qa_contact_sheet.jpg
    │   └── visual_review.json
    ├── work/
    │   ├── imagegen_raw/
    │   └── derivative_crops/
    └── Flagged by Culture-Aware QA/

• final/: upload-ready assets only.
• qa/: manifest, contact sheet, QA notes, and logs.
• work/: model raw outputs, experiments, temporary scripts, and deterministic crop intermediates.
• source/: a copy of the original input image for traceability.
• Flagged by Culture-Aware QA/: files that need local review before launch.

How It Is Different

This is not a general image translation tool.

Most image translation projects focus on OCR, text removal, translation, and re-rendering. This skill focuses on ad creative localization delivery: translating in-image copy, preserving brand/product terms, adapting to common ad sizes, generating upload-ready filenames, writing manifests, and running visual QA inside a Codex workflow.

For Arabic and other RTL languages, the skill first attempts true RTL-aware layout adaptation, and falls back to copy-only localization if QA determines the adapted layout is weaker.

RTL-aware Localization

For Arabic and other right-to-left languages, the skill uses a quality-first fallback strategy: create a true RTL-aware layout first, then fall back to copy-only localization only when the adapted layout is less natural, less readable, or less brand-safe.

• Option A: RTL-aware enabled (default for RTL languages): right-aligns primary RTL copy, makes the information flow start from the right, adapts CTA placement/direction, and adjusts local UI, dialogue, product, or subject relationships when needed for right-to-left reading.
• Option B: RTL-aware disabled / fallback: translates visible copy only and preserves the original layout structure when layout adaptation reduces quality.

Use Option A by default for Arabic and other RTL languages. Use Option B when a true RTL-aware layout makes the creative feel unbalanced, damages brand recognition, or produces weaker text layout. RTL-aware localization is not a request to mirror the entire design, flip logos, or move brand identity without a clear visual reason.

RTL-aware QA should reject outputs where the main Arabic/RTL headline, body, or CTA is left-aligned or merely centered without a clear reason; where the visual reading path still starts on the left; or where Arabic + Latin brand/product text has awkward visual order. If the final output keeps a mostly LTR composition, note why and state whether it is the copy-only fallback.

Culture-Aware QA

During QA, the skill also checks whether a localized creative may create cultural, legal, religious, social, or political risk in the target market. This is a review flag, not automatic creative editing and not legal advice.

Examples of things the check may consider include religious sensitivity, regulated claims, disputed borders or maps, political symbols, gestures, food or animal symbolism, modesty norms, and local advertising restrictions. It does not use a fixed blacklist; the judgment depends on the creative, language, target market, and product category. When the risk depends on current market rules or political context, Codex should search for current sources before flagging.

If a variant is flagged, the skill moves the affected files into:

Flagged by Culture-Aware QA/

The user should review those files before launch or ask Codex to create a safer revision. The skill does not modify flagged creatives unless the user explicitly asks.

Helper Script

The bundled Python helper handles deterministic last-mile work after model-native output exists. It does not call an image API and does not replace Codex imagegen or built-in image generation.

RUN=ad-localization-runs/rabbit-social-networks_20260623_1430
python3 -m pip install -r skills/ad-image-localization/requirements.txt
python3 skills/ad-image-localization/scripts/ad_image_localization_tools.py preflight examples/job.example.json --output "$RUN/qa/preflight.json"
python3 skills/ad-image-localization/scripts/ad_image_localization_tools.py cover-crop "$RUN/work/imagegen_raw/input_16x9.png" "$RUN/final/rabbit-social-networks_en_1200x628_20260623.png" --size 1200x628
python3 skills/ad-image-localization/scripts/ad_image_localization_tools.py manifest "$RUN/final" --plan "$RUN/qa/preflight.json" --output "$RUN/qa/manifest.json"
python3 skills/ad-image-localization/scripts/ad_image_localization_tools.py verify "$RUN/final"
python3 skills/ad-image-localization/scripts/ad_image_localization_tools.py contact-sheet "$RUN/final" "$RUN/qa/qa_contact_sheet.jpg"
python3 skills/ad-image-localization/scripts/ad_image_localization_tools.py qa-init "$RUN/final" --plan "$RUN/qa/preflight.json" --output "$RUN/qa/visual_review.json"
python3 skills/ad-image-localization/scripts/ad_image_localization_tools.py release-check "$RUN/final" --review "$RUN/qa/visual_review.json"
python3 skills/ad-image-localization/scripts/ad_image_localization_tools.py flag-culture-aware "$RUN/final" rabbit-social-networks_ar_1200x628_20260623.png --destination "../Flagged by Culture-Aware QA" --market "GCC" --reason "Needs local cultural review"
python3 skills/ad-image-localization/scripts/ad_image_localization_tools.py memory-add skills/ad-image-localization/brand_term_memory.json --brand openai --term Codex --action preserve

Use preflight before generation, then use the other commands after model-native output exists. The QA commands do not inspect pixels automatically: qa-init creates the review record and release-check blocks incomplete, failed, or unexplained flagged reviews. Do not use the helper to create the primary 1:1, 16:9, 4:5, or 9:16 anchors; those should be generated with imagegen.

Local helper tests:

python3 -m pip install -r skills/ad-image-localization/requirements.txt
python3 -m unittest discover -s tests
python3 skills/ad-image-localization/scripts/ad_image_localization_tools.py verify examples/verified-delivery-pack

Installation

This is a Codex-only plugin. Install it through the Codex plugin marketplace flow so Codex loads the bundled skill, helper scripts, examples, and plugin metadata together.

Recommended CLI Install

codex plugin marketplace add kouzt123/ad-image-localization-codex
codex plugin add ad-image-localization-codex@kouzt123-plugins

Restart Codex or start a new thread after installation.

Easiest Option

Ask Codex to install it for you:

Help me install this Codex plugin: https://github.com/kouzt123/ad-image-localization-codex

Codex can use the marketplace file in this repo, install the plugin, and tell you when to restart or refresh.

This project is distributed as a Codex plugin, not a generic cross-agent skill package.

See install.md for setup, verification, and update notes.

Usage

In Codex, ask for the skill explicitly:

Use ad-image-localization to translate this game ad into German, French, Spanish, Japanese, and Korean. Export 1200x1200, 1920x1080, 1080x1350, 1080x1920, and 1200x628.

Other examples:

Localize this poster into Arabic and Vietnamese. Preserve the product name in English and make sure the 1200x628 output does not stretch the text.

For Arabic, create a true RTL-aware layout first: right-aligned Arabic copy, right-side information priority, and RTL CTA flow. If QA finds that true RTL layout weaker, use copy-only localization and preserve the original overall layout.

During QA, run Culture-Aware QA for the target markets. If a localized variant may need local review, move its affected sizes into Flagged by Culture-Aware QA/ and tell me why.

To teach terminology memory, describe the brand or product scope:

Remember this terminology rule for Example Brand: keep "PixelPass" in English for all localized assets.

Prompt Cookbook

Game Ad

Use ad-image-localization to localize this game ad into German, Spanish, Japanese, and Arabic. Preserve the game title, translate all character traits and UI labels, and export 1200x1200, 1920x1080, 1080x1350, 1080x1920, and 1200x628.

For Arabic and other RTL languages, the skill first attempts true RTL-aware layout adaptation with right-aligned primary copy and right-to-left reading flow, then falls back to copy-only localization if QA determines the adapted layout is weaker.

Ecommerce Product Image

Use ad-image-localization to create French and Portuguese versions of this product banner. Keep the brand name unchanged, localize the offer text, and output Meta feed, story, and 1200x628 link-ad sizes.

SaaS Banner

Use ad-image-localization to localize this SaaS launch banner into Japanese and Korean. Keep product UI readable, preserve the logo, and generate 16:9 plus 1200x628 with safe margins.

App Store / Social Screenshot

Use ad-image-localization to turn these app screenshots into Indonesian and Vietnamese campaign creatives. Translate visible marketing copy, keep UI labels natural, and export upload-ready filenames with manifest.json.

Size Handling

Platform support and default delivery resolution are separate concepts. Plan by aspect ratio first, then use one canonical resolution for delivery. Two platform presets that both request 1:1 reuse one model-native square; an additional exact square size is a deterministic same-ratio resize.

The standard profile delivers five files per language from four model-native anchors:

• 1200x1200 — 1:1 model-native
• 1920x1080 — 16:9 model-native and still delivered to the user
• 1080x1350 — 4:5 model-native
• 1080x1920 — 9:16 model-native
• 1200x628 — deterministic derivative of the delivered 16:9 anchor

Always inspect the actual ratio returned by the image model before pixel normalization. If a requested 4:5 comes back as another portrait ratio, regenerate once with an explicit exact-ratio correction; never stretch it across ratios.

For special close-ratio sizes such as 1200x628, the recommended deterministic derivative workflow is:

1. Generate a strong 16:9 version with top/bottom safe margins.
2. Resize proportionally from 1920x1080 to 1200x675.
3. Crop the vertical overflow to 1200x628.

This preserves geometry and avoids non-uniform stretching.

The helper script exposes this as a reusable command:

python3 skills/ad-image-localization/scripts/ad_image_localization_tools.py cover-crop 1920x1080.png 1200x628.png --size 1200x628

Use normalize-size for another resolution in the same ratio, such as 1200x1200 to 1080x1080; it refuses cross-ratio requests.

For a broad Google request, google-ads-image-assets uses the current Google Ads image-asset terminology: horizontal 1.91:1 with 1200x628 as a recommended size. The extra delivered 1920x1080 remains this skill's safe model-generation anchor, not a claimed Google requirement. Campaign-specific rules should still be checked at run time.

Terminology Memory

The skill supports a JSON memory file for user-approved terminology:

{
  "version": 1,
  "brands": {
    "example-brand": {
      "display_name": "Example Brand",
      "rules": [
        {"term": "Example Brand", "action": "preserve"}
      ],
      "products": {}
    }
  }
}

Rule priority is brand, then product, then an explicit current-job instruction. The later layer wins for the same term.

Repository Structure

ad-image-localization-codex/
├── .codex-plugin/
│   └── plugin.json
├── .agents/
│   └── plugins/
│       └── marketplace.json
├── README.md
├── README.zh-CN.md
├── install.md
├── LICENSE
├── skills/
│   └── ad-image-localization/
│       ├── SKILL.md
│       ├── assets/
│       ├── references/
│       ├── requirements.txt
│       ├── scripts/
│       │   └── ad_image_localization_tools.py
│       ├── brand_term_memory.json
│       └── agents/
│           └── openai.yaml
├── tests/
├── evals/
├── examples/
└── scripts/
    └── setup-codex-attribution.sh

Runtime outputs are intentionally ignored by Git under ad-localization-runs/.

License

MIT. See LICENSE.