claude-plugin-wordpress-manager 1.4.0 → 1.7.0

package/skills/wp-i18n/references/multilingual-setup.md

@@ -0,0 +1,219 @@
+# Multilingual Setup
+
+Use this file when configuring WordPress for multilingual content delivery.
+
+## Plugin-based solutions
+
+### WPML (commercial)
+
+Most widely used. Supports posts, pages, custom post types, taxonomies, strings, menus, and widgets.
+
+```php
+// Check if WPML is active
+if (defined('ICL_SITEPRESS_VERSION')) {
+    // WPML-specific code
+}
+
+// Get current language
+$current_lang = apply_filters('wpml_current_language', null);
+
+// Get element translation
+$translated_id = apply_filters('wpml_object_id', $post_id, 'post', true, 'it');
+
+// Switch language in a template
+do_action('wpml_switch_lang', 'it');
+// ... output Italian content
+do_action('wpml_switch_lang', null); // reset
+```
+
+Theme/plugin compatibility header:
+```php
+/**
+ * Plugin Name: My Plugin
+ * WPML Compatible: yes
+ */
+```
+
+### Polylang (free + pro)
+
+```php
+// Check if Polylang is active
+if (function_exists('pll_current_language')) {
+    $lang = pll_current_language();
+}
+
+// Get translated post ID
+$translated_id = pll_get_post($post_id, 'it');
+
+// Get translated term ID
+$translated_term = pll_get_term($term_id, 'it');
+
+// Register a string for translation
+pll_register_string('my-string-name', 'Default text', 'My Plugin');
+
+// Get translated string
+$text = pll__('Default text');
+// or echo
+pll_e('Default text');
+```
+
+### TranslatePress (visual)
+
+Frontend visual editing — translates directly on the page.
+
+```php
+// Check if TranslatePress is active
+if (class_exists('TRP_Translate_Press')) {
+    // TranslatePress-specific code
+}
+```
+
+## URL structure options
+
+| Strategy | Example | Pros | Cons |
+|----------|---------|------|------|
+| Subdirectories | `example.com/it/` | Simple, single domain | Shared hosting limits |
+| Subdomains | `it.example.com` | Separate analytics | DNS setup required |
+| Domains | `example.it` | Best for SEO by country | Multiple SSL certs |
+| URL parameter | `example.com?lang=it` | Easiest setup | Worst for SEO |
+
+Recommended: **subdirectories** for most projects.
+
+## Making plugins translation-compatible
+
+### String registration (WPML)
+
+```php
+// Register admin strings
+add_action('init', function() {
+    if (function_exists('icl_register_string')) {
+        icl_register_string('my-plugin', 'CTA Button Text', get_option('my_cta_text'));
+    }
+});
+
+// Retrieve translated string
+function get_my_cta_text() {
+    $text = get_option('my_cta_text');
+    if (function_exists('icl_t')) {
+        return icl_t('my-plugin', 'CTA Button Text', $text);
+    }
+    return $text;
+}
+```
+
+### wpml-config.xml
+
+Required for WPML to know which custom fields and options to translate:
+
+```xml
+<wpml-config>
+    <custom-fields>
+        <custom-field action="translate">subtitle</custom-field>
+        <custom-field action="copy">price</custom-field>
+        <custom-field action="ignore">internal_notes</custom-field>
+    </custom-fields>
+    <admin-texts>
+        <key name="my_plugin_options">
+            <key name="cta_text" />
+            <key name="footer_text" />
+        </key>
+    </admin-texts>
+    <custom-types>
+        <custom-type translate="1">product</custom-type>
+    </custom-types>
+    <taxonomies>
+        <taxonomy translate="1">product_category</taxonomy>
+    </taxonomies>
+</wpml-config>
+```
+
+Place at plugin or theme root. WPML reads it automatically.
+
+## Multilingual REST API
+
+### WPML
+
+```bash
+# Get posts in Italian
+curl "https://site.com/wp-json/wp/v2/posts?lang=it"
+
+# Requires WPML REST API addon or custom filter
+```
+
+### Polylang
+
+```bash
+# Polylang adds ?lang= support to REST API
+curl "https://site.com/wp-json/wp/v2/posts?lang=it"
+```
+
+### Custom REST language filtering
+
+```php
+add_filter('rest_post_query', function($args, $request) {
+    $lang = $request->get_param('lang');
+    if ($lang && function_exists('pll_current_language')) {
+        $args['lang'] = $lang;
+    }
+    return $args;
+}, 10, 2);
+```
+
+## hreflang tags
+
+Essential for SEO — tells search engines which language version to show:
+
+```php
+add_action('wp_head', function() {
+    // WPML handles this automatically
+    // For custom implementations:
+    $languages = [
+        'en' => 'https://example.com/page/',
+        'it' => 'https://example.com/it/pagina/',
+        'de' => 'https://example.com/de/seite/',
+    ];
+    foreach ($languages as $lang => $url) {
+        printf('<link rel="alternate" hreflang="%s" href="%s" />' . "\n",
+            esc_attr($lang), esc_url($url));
+    }
+    // x-default for language selector/default page
+    printf('<link rel="alternate" hreflang="x-default" href="%s" />' . "\n",
+        esc_url($languages['en']));
+});
+```
+
+## WooCommerce multilingual
+
+### WPML + WooCommerce Multilingual
+
+- Synchronizes products, variations, attributes across languages
+- Multi-currency support
+- Translated emails and checkout
+
+```php
+// Get translated product ID
+$translated_product_id = apply_filters('wpml_object_id', $product_id, 'product', true, 'it');
+
+// Get price in current currency
+// Handled automatically by WooCommerce Multilingual
+```
+
+### Polylang + Hyyan WooCommerce Polylang Integration
+
+Free alternative. Syncs stock, prices, and product data.
+
+## Verification
+
+```bash
+# Check hreflang tags
+curl -s https://site.com/ | grep -i "hreflang"
+
+# Verify language switcher works
+curl -s -o /dev/null -w "%{http_code}" https://site.com/it/
+
+# Check WPML config file exists (for WPML-compatible plugins)
+ls wpml-config.xml
+
+# Verify translated content exists
+wp post list --lang=it --post_type=page --fields=ID,post_title
+```

package/skills/wp-i18n/references/php-i18n.md

@@ -0,0 +1,196 @@
+# PHP Internationalization
+
+Use this file when internationalizing PHP code in WordPress plugins and themes.
+
+## Core translation functions
+
+### Simple strings
+
+```php
+// Return translated string
+$text = __('Hello World', 'my-text-domain');
+
+// Echo translated string
+_e('Hello World', 'my-text-domain');
+```
+
+### Strings with context
+
+```php
+// "Post" as a verb vs noun
+$verb = _x('Post', 'verb', 'my-text-domain');
+$noun = _x('Post', 'noun', 'my-text-domain');
+
+// Echo version
+_ex('Post', 'verb', 'my-text-domain');
+```
+
+### Strings with variables
+
+```php
+// Single placeholder
+$text = sprintf(
+    /* translators: %s: user display name */
+    __('Welcome, %s!', 'my-text-domain'),
+    $user->display_name
+);
+
+// Multiple placeholders (use numbered)
+$text = sprintf(
+    /* translators: 1: product name, 2: price */
+    __('%1$s costs %2$s', 'my-text-domain'),
+    $product_name,
+    $price
+);
+```
+
+### Plurals
+
+```php
+$text = sprintf(
+    /* translators: %d: number of items */
+    _n('%d item', '%d items', $count, 'my-text-domain'),
+    $count
+);
+
+// With context
+$text = sprintf(
+    _nx('%d post', '%d posts', $count, 'blog posts', 'my-text-domain'),
+    $count
+);
+```
+
+## Escaping functions
+
+Always use escaping variants when outputting to HTML:
+
+```php
+// Escape for HTML content
+echo esc_html__('Safe text', 'my-text-domain');
+esc_html_e('Safe text', 'my-text-domain');
+
+// Escape for HTML attributes
+echo esc_attr__('attribute value', 'my-text-domain');
+esc_attr_e('attribute value', 'my-text-domain');
+
+// With context
+echo esc_html_x('Post', 'verb', 'my-text-domain');
+```
+
+### When to use which
+
+| Context | Function |
+|---------|----------|
+| HTML content | `esc_html__()` / `esc_html_e()` |
+| HTML attributes | `esc_attr__()` / `esc_attr_e()` |
+| URLs | `esc_url()` around `__()` |
+| JavaScript strings | `esc_js()` around `__()` |
+| Already-safe internal use | `__()` / `_e()` |
+
+## Text domain loading
+
+### Plugins
+
+```php
+add_action('init', function() {
+    load_plugin_textdomain(
+        'my-text-domain',
+        false,
+        dirname(plugin_basename(__FILE__)) . '/languages'
+    );
+});
+```
+
+### Themes
+
+```php
+add_action('after_setup_theme', function() {
+    load_theme_textdomain(
+        'my-text-domain',
+        get_template_directory() . '/languages'
+    );
+});
+
+// Child theme
+add_action('after_setup_theme', function() {
+    load_child_theme_textdomain(
+        'my-child-domain',
+        get_stylesheet_directory() . '/languages'
+    );
+});
+```
+
+### WordPress 6.7+ (automatic loading)
+
+Since WordPress 6.7, translation files placed in `wp-content/languages/plugins/` or `wp-content/languages/themes/` are loaded automatically. Manual `load_plugin_textdomain()` is still recommended as a fallback.
+
+## Common mistakes
+
+### Do NOT concatenate translatable strings
+
+```php
+// WRONG — translators cannot reorder
+__('There are ' . $count . ' items', 'my-text-domain');
+
+// CORRECT
+sprintf(__('There are %d items', 'my-text-domain'), $count);
+```
+
+### Do NOT use variables as text domain
+
+```php
+// WRONG — tools cannot extract
+__('Hello', $domain);
+
+// CORRECT — literal string only
+__('Hello', 'my-text-domain');
+```
+
+### Do NOT translate HTML
+
+```php
+// WRONG — HTML in translatable string
+__('<strong>Warning:</strong> This is dangerous', 'my-text-domain');
+
+// CORRECT — separate HTML from text
+'<strong>' . esc_html__('Warning:', 'my-text-domain') . '</strong> '
+    . esc_html__('This is dangerous', 'my-text-domain');
+```
+
+### Do NOT split sentences
+
+```php
+// WRONG — sentence split across calls
+__('Click ', 'my-text-domain') . '<a>' . __('here', 'my-text-domain') . '</a>';
+
+// CORRECT — full sentence with placeholder
+sprintf(
+    /* translators: %s: link HTML */
+    __('Click %s for details', 'my-text-domain'),
+    '<a href="...">' . esc_html__('here', 'my-text-domain') . '</a>'
+);
+```
+
+## Translator comments
+
+Add context for translators with `/* translators: */` comments:
+
+```php
+/* translators: %s: date in ISO 8601 format */
+sprintf(__('Published on %s', 'my-text-domain'), $date);
+
+/* translators: 1: opening link tag, 2: closing link tag */
+sprintf(__('Read the %1$sfull article%2$s', 'my-text-domain'), '<a href="...">', '</a>');
+```
+
+These comments must appear on the line immediately before the translation function call.
+
+## Verification
+
+```bash
+# Check for missing text domains
+wp i18n make-pot . languages/my-text-domain.pot --slug=my-text-domain
+
+# Audit for untranslated strings
+grep -rn "echo \"\|echo '" --include="*.php" | grep -v "__\|_e\|esc_"
+```

package/skills/wp-i18n/references/rtl-support.md

@@ -0,0 +1,206 @@
+# RTL (Right-to-Left) Support
+
+Use this file when adding right-to-left language support to WordPress themes and plugins.
+
+## RTL languages
+
+Arabic (`ar`), Hebrew (`he`), Persian/Farsi (`fa`), Urdu (`ur`), Pashto (`ps`), Sindhi (`sd`), Kurdish (Sorani) (`ckb`), Uyghur (`ug`), Divehi (`dv`).
+
+## How WordPress handles RTL
+
+WordPress automatically:
+1. Sets `dir="rtl"` on `<html>` when the locale is RTL
+2. Adds `class="rtl"` to `<body>`
+3. Loads `*-rtl.css` stylesheets (if they exist) instead of `*.css`
+
+Check direction in PHP:
+```php
+if (is_rtl()) {
+    // RTL-specific logic
+}
+```
+
+Check in JavaScript:
+```js
+const isRtl = document.documentElement.dir === 'rtl';
+// or
+const isRtl = document.body.classList.contains('rtl');
+```
+
+## CSS approach: Logical properties (recommended)
+
+Modern CSS logical properties handle both LTR and RTL automatically:
+
+```css
+/* AVOID physical properties */
+.card {
+    margin-left: 20px;      /* LTR only */
+    padding-right: 10px;    /* LTR only */
+    text-align: left;       /* LTR only */
+    float: left;            /* LTR only */
+    border-left: 1px solid; /* LTR only */
+}
+
+/* USE logical properties */
+.card {
+    margin-inline-start: 20px;     /* left in LTR, right in RTL */
+    padding-inline-end: 10px;      /* right in LTR, left in RTL */
+    text-align: start;             /* left in LTR, right in RTL */
+    float: inline-start;           /* left in LTR, right in RTL */
+    border-inline-start: 1px solid; /* left in LTR, right in RTL */
+}
+```
+
+### Logical property mapping
+
+| Physical | Logical | LTR | RTL |
+|----------|---------|-----|-----|
+| `left` | `inline-start` | left | right |
+| `right` | `inline-end` | right | left |
+| `margin-left` | `margin-inline-start` | margin-left | margin-right |
+| `margin-right` | `margin-inline-end` | margin-right | margin-left |
+| `padding-left` | `padding-inline-start` | padding-left | padding-right |
+| `padding-right` | `padding-inline-end` | padding-right | padding-left |
+| `border-left` | `border-inline-start` | border-left | border-right |
+| `text-align: left` | `text-align: start` | left | right |
+| `float: left` | `float: inline-start` | left | right |
+
+### Shorthand
+
+```css
+/* Physical: top right bottom left */
+margin: 10px 20px 10px 0;
+
+/* Logical */
+margin-block: 10px;         /* top and bottom */
+margin-inline: 0 20px;      /* start and end */
+```
+
+## CSS approach: RTL stylesheets (legacy)
+
+### Automatic RTL generation
+
+```bash
+# Generate RTL stylesheets with rtlcss
+npx rtlcss style.css style-rtl.css
+
+# Watch mode
+npx rtlcss -w src/style.css dist/style-rtl.css
+```
+
+### rtlcss directives
+
+Control flipping with comments:
+
+```css
+/* rtl:ignore — skip this rule */
+.icon-arrow {
+    /* rtl:ignore */
+    transform: rotate(45deg);
+}
+
+/* rtl:remove — remove this rule in RTL */
+.ltr-only {
+    /* rtl:remove */
+    float: left;
+}
+
+/* rtl:raw — insert raw CSS in RTL */
+.custom {
+    /* rtl:raw:
+    float: right;
+    */
+}
+```
+
+### Enqueuing RTL stylesheets
+
+WordPress handles this automatically when you enqueue properly:
+
+```php
+wp_enqueue_style('my-style', plugins_url('css/style.css', __FILE__));
+// WordPress will automatically load css/style-rtl.css in RTL contexts
+// IF the RTL file exists in the same directory
+```
+
+For custom paths:
+```php
+wp_style_add_data('my-style', 'rtl', 'replace');
+// WordPress will load style-rtl.css instead of style.css
+```
+
+Or add an independent RTL stylesheet:
+```php
+wp_style_add_data('my-style', 'rtl', plugin_dir_url(__FILE__) . 'css/custom-rtl.css');
+```
+
+## Block editor RTL support
+
+### Block styles
+
+```css
+/* Use logical properties in block stylesheets */
+.wp-block-my-plugin-card {
+    padding-inline-start: 1rem;
+    border-inline-start: 3px solid var(--wp--preset--color--primary);
+}
+```
+
+### useBlockProps and direction
+
+```js
+import { useBlockProps } from '@wordpress/block-editor';
+
+export default function Edit() {
+    const blockProps = useBlockProps();
+    // blockProps automatically inherits the document direction
+    return <div {...blockProps}>Content</div>;
+}
+```
+
+## Icons and directional elements
+
+Flip directional icons in RTL:
+
+```css
+/* Arrows, chevrons, navigation icons */
+.rtl .icon-arrow-right {
+    transform: scaleX(-1);
+}
+
+/* Or with logical approach */
+[dir="rtl"] .icon-next {
+    transform: scaleX(-1);
+}
+```
+
+Do NOT flip:
+- Clocks (always clockwise)
+- Media playback controls (play/pause universal)
+- Checkmarks
+- Phone icons
+- Logos and brand marks
+
+## Testing RTL
+
+```bash
+# Switch site to Arabic
+wp site switch-language ar
+
+# Switch back to English
+wp site switch-language en_US
+```
+
+Quick browser test: add `dir="rtl"` to `<html>` in DevTools.
+
+WordPress admin: Settings → General → Site Language → Arabic (or any RTL language).
+
+## Verification checklist
+
+- [ ] All CSS uses logical properties (or RTL stylesheets exist)
+- [ ] No hardcoded `left`/`right` in positioning
+- [ ] Directional icons flip correctly
+- [ ] Text alignment uses `start`/`end` not `left`/`right`
+- [ ] Flexbox/Grid layout respects direction
+- [ ] RTL stylesheets are properly enqueued with `wp_style_add_data`
+- [ ] Tested with at least one RTL locale (Arabic recommended)