# Translatepress Output Compatibility
> Audit or implement WordPress plugin/theme output so TranslatePress can translate it correctly. Use when code must be compatible with TranslatePress visual translation, gettext string translation, dynamic JS-inserted text, automatic translation exclusions, AJAX/REST-rendered fragments, language-aware caches, or user-facing text generated by shortcodes, widgets, forms, WooCommerce templates, page builders, or theme templates.
- Skill: `lonsdale201/translatepress-output-compatibility` (Agent Skill)
- Install (CLI): `npx skillmds@latest add lonsdale201/translatepress-output-compatibility`
- Raw SKILL.md: https://api.skillmd.com/api/skills/lonsdale201/translatepress-output-compatibility/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Security
- License: GPLv2-or-later
- Author: Lonsdale201 (https://skillmd.com/u/lonsdale201)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/lonsdale201/translatepress-output-compatibility
---
# TranslatePress Output Compatibility
TranslatePress translates the rendered front-end page, plus gettext strings and dynamic strings it can detect. Build plugin/theme output as stable, accessible, server-rendered HTML first; then add explicit exclusions only for values that must never be translated.
## When to use this skill
Trigger when ANY of the following is true:
- A plugin/theme must be "TranslatePress-compatible".
- User-facing text is generated by PHP templates, shortcodes, widgets, AJAX, REST, JS, WooCommerce templates, form builders, or page-builder integrations.
- Code uses dynamic labels, generated HTML fragments, language-specific caches, or strings that should be excluded from translation.
- The task mentions `data-no-translation`, `data-no-dynamic-translation`, `data-no-auto-translation`, `trp_no_translate_selectors`, `trp_no_auto_translate_selectors`, `trp_skip_selectors_from_dynamic_translation`, gettext strings, or TranslatePress automatic translation.
## Baseline checks
Verify the installed stack before debugging compatibility:
```bash
wp plugin list --fields=name,status,version | grep -E 'translatepress'
wp eval 'echo defined( "TRP_PLUGIN_VERSION" ) ? TRP_PLUGIN_VERSION : "missing-core";'
wp option get trp_settings --format=json
wp option get trp_add_ons_settings --format=json
```
TranslatePress Multilingual 3.2.1 and Business 1.8.2 are the validated versions for this skill. The Business loader blocks TranslatePress when the core version is below `2.8.7`, shows a settings-redesign notice below `2.9.7`, and loads add-ons from `trp_add_ons_settings`.
## Make text discoverable
Render translatable text as real front-end text, not as opaque data:
```php
printf(
'
%s
',
esc_html__( 'Your booking is confirmed.', 'myplugin' )
);
```
Use normal WordPress i18n functions for plugin/theme UI strings. TranslatePress can translate gettext strings, and site owners may also choose to disable TranslatePress gettext translation so `.po/.mo` files handle them.
For user-configured copy stored in options, output the saved text plainly:
```php
$message = get_option( 'myplugin_checkout_message', '' );
if ( $message !== '' ) {
echo wp_kses_post( wpautop( $message ) );
}
```
Do not store per-language copies in your own option unless the product explicitly owns a multilingual content model. Let TranslatePress translate rendered output.
## Dynamic JS output
TranslatePress can detect client-side changes, but do not make it guess around unstable markup:
- Insert complete phrases, not sentence fragments spread across multiple async updates.
- Prefer server-rendered HTML for initial state, then update only values that really changed.
- Keep selectors stable; avoid replacing the entire app root on every interaction.
- For REST/AJAX fragments that return HTML, include the current language in cache keys and test the response in each language URL.
Language-aware cache key pattern:
```php
$language = isset( $GLOBALS['TRP_LANGUAGE'] ) ? (string) $GLOBALS['TRP_LANGUAGE'] : get_locale();
$cache_key = 'myplugin_card_' . md5( $language . '|' . wp_json_encode( $args ) );
```
Never cache translated front-end HTML globally without varying by language and, when Different Domain per Language is active, by host.
## Exclude text deliberately
Use exclusion attributes only for strings that should remain literal:
```php
echo '' . esc_html( $license_key_mask ) . '';
echo '' . esc_html( $brand_name ) . '';
echo '';
```
Meanings:
| Attribute | Use for |
|---|---|
| `data-no-translation` | Never translate this element or its children. |
| `data-no-auto-translation` | Allow manual handling, but exclude from automatic translation. |
| `data-no-dynamic-translation` | Skip JS dynamic detection while still allowing server-side translation when possible. |
| `data-no-translation-href` | Prevent TranslatePress from translating a specific link URL. |
Programmatic selector exclusions:
```php
add_filter( 'trp_no_translate_selectors', static function ( array $selectors, string $language ): array {
$selectors[] = '.myplugin-code-sample';
return $selectors;
}, 10, 2 );
add_filter( 'trp_skip_selectors_from_dynamic_translation', static function ( array $selectors ): array {
$selectors[] = '.myplugin-live-region';
return $selectors;
} );
add_filter( 'trp_no_auto_translate_selectors', static function ( array $selectors, string $language ): array {
$selectors[] = '.myplugin-brand-copy';
return $selectors;
}, 10, 2 );
```
Do not use broad selectors like `.content`, `main`, or `.product`; they hide too much from translation.
## Forms, nonces, and volatile values
Mark volatile technical values as not translatable:
- nonces and tokens;
- IDs, SKUs, license keys, API keys, hashes;
- machine-readable status codes;
- JSON embedded in HTML attributes;
- timestamps that are recalculated every request.
Good pattern:
```php
printf(
'',
esc_attr( wp_create_nonce( 'myplugin_action' ) )
);
```
Do not put translatable prose inside `value` attributes when a visible `