Automatic Multi-Language Alt Text (OpenAI)

CONTENTS

A. Overview B. Requirements & Compatibility C. Installation D. Licensing & Updates E. Basic Settings F. Usage Modes G. Nightly Auto‑Fill (CRON) H. WPML & Language Logic I. Security & Privacy J. Troubleshooting K. FAQ

A) Overview

Lieska Multi‑Language Alt Text (OpenAI) generates accessible ALT text for images inside WordPress. It supports multiple languages and per‑language ALT texts with WPML. Features include:

• Bulk generation in Media Library (with optional Overwrite).
• Auto‑generation on upload.
• Button in the Media modal beside the ALT field.
• Gutenberg Image block panel with Overwrite & Regenerate.
• Optional nightly WP‑Cron job to fill missing ALTs.

B) Requirements & Compatibility

• A modern WordPress version (block editor recommended).
• OpenAI API key required.
• WPML (optional) for per‑language attachment ALTs. Without WPML, the configured language list is used in a simplified way.
• Capabilities: settings pages need manage_options; generation buttons require upload_files.

C) Installation

1. Upload and activate the plugin (Plugins → Add New → Upload ZIP → Activate).
2. After activation you’ll be redirected once to the licensing screen.
3. Enter your license (see D) and save.
4. Open Settings → AI Alt Text (OpenAI) and add your OpenAI API key.
5. Save settings.

D) Licensing & Updates

• Manage license at Settings → Lieska Plugin Licenses, anchor #lieska-ml-alt.
• Enter your license key to enable one‑click updates.
• The updates panel will show license errors if any, with a link to the license screen.

E) Basic Settings

Settings page: Settings → AI Alt Text (OpenAI)

• OpenAI API key: required.
• Model: e.g., gpt-4o-mini (default). Adjustable.
• Languages (WPML codes): comma‑separated, e.g., fi,sv,en.
• Prompt template: use {{LANG}} and {{FILENAME}}. Default prompt outputs a single, concise sentence without quotes.
• Max tokens: e.g., 75.
• Auto generate on upload: when enabled, generates for the image’s WPML language immediately on upload.

Nightly auto‑fill (WP‑Cron) – quick

• Enable nightly auto‑fill: turn the job on.
• Run time (HH:MM): in the site’s timezone.
• Batch size: how many images per run.
• Overwrite existing?: if enabled, replaces existing ALTs.
• See Next run / Last run and a Run now button.

F) Usage Modes

a) Media Library (Bulk actions)

• Go to Media → Library (list view), select images.
• Choose bulk action:
  • Generate AI Alt (current lang: XX)
  • Generate AI Alt (overwrite, current lang: XX)
• “Current lang” is the current WPML admin language.

b) Attachment Edit Screen (Metabox)

• Open an individual image.
• In the side metabox AI Alt Text (OpenAI, multi‑lang):
  • Tick languages and optional Overwrite.
  • Click Generate now.

c) Media Modal

• In the media modal, a Generate AI Alt (lang: XX) button appears under the ALT field once an image is selected.
• Clicking it generates ALT and inserts it straight into the field.

d) Gutenberg Image Block

• Select a core/image block.
• On the right Block tab you’ll see AI Alt (OpenAI) panel with:
  • Generate AI Alt (lang: XX)
  • ↻ Regenerate
  • Overwrite existing

e) Auto on Upload

• With Auto generate on upload enabled, the ALT is generated immediately for the image’s own WPML language.

G) Nightly Auto‑Fill (CRON) – details

• When enabled, the job finds images missing ALT (or all images if Overwrite is on).
• Processes up to Batch size images per run.
• Run now triggers the same logic immediately.
• Tip: on low‑traffic sites, WP‑Cron may be delayed. Add a real cron to ping wp-cron.php every 10 minutes:
  */10 * * * * curl -s https://example.com/wp-cron.php?doing_wp_cron=1 > /dev/null 2>&1

H) WPML & Language Logic

• Metabox (multi‑lang): generates for multiple languages in one go, saving into each language’s attachment translation when available (fallback: source attachment).
• Bulk, block panel & media modal: use the current admin language code.
• Without WPML, the Languages list still controls selections but data is stored on the base attachment.

I) Security & Privacy

• Calls to OpenAI are made server‑side with your key.
• The key is stored in the WordPress options table.
• The image is sent as base64 data when feasible (≤ ~10 MB), otherwise by image URL.
• Only the _wp_attachment_image_alt meta is written.

J) Troubleshooting

• Missing API key: add the key in settings.
• Not an image / No image URL: check the item and its full‑size URL.
• HTTP / OpenAI error: verify model name, key validity, timeouts, and firewall rules.
• Button not visible in modal: reopen the modal; ensure the ALT field section is visible.
• Nightly job not firing: ensure WP‑Cron is active or add a real cron (see above).

K) FAQ

• Will it overwrite existing ALTs? Only with Overwrite enabled (or in nightly job when its overwrite is enabled).
• Does it alter image files? No—only the ALT meta.
• Can I change the prompt? Yes; keep {{LANG}} and {{FILENAME}} placeholders as needed.
• Which language codes? Use WPML codes (e.g., fi, sv, en).
• What about large images? Over ~10 MB are sent by URL, which may be slower if remote fetch is restricted.

Quick steps to create an API key

1. Go to platform.openai.com → Account → API keys. platform.openai.com

2. If you use Projects/Organizations, pick the correct project first. OpenAI Help Center

3. Click Create new secret key, name it, and copy it (shown once). OpenAI Help Center+1

4. (Optional) Configure permissions and usage limits at the project/billing level. OpenAI Help Center

5. Paste it in WordPress at Settings → AI Alt Text (OpenAI) → OpenAI API key → Save.

Security: never expose keys in public repos or client-side code; rotate/delete on compromise; separate keys per env and set caps.