Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

iTechGuides is reader-supported. When you buy through links on our site, we may earn an affiliate commission. As an Amazon Associate I earn from qualifying purchases. Learn more

Internationalizing a WordPress block theme means giving every user-facing string a consistent text domain, translating both PHP-rendered and editor-side JavaScript text, extracting catalogs with WP-CLI, loading the resulting files from the right locations, and testing the theme in a target locale. A block theme does not become translation-ready automatically just because its templates are made of blocks.

What internationalization changes in a block theme

A block theme is assembled mainly from block templates, template parts, patterns, a theme.json configuration file and editor-side code. Text can therefore be emitted in several places: PHP files, pattern files, block markup and JavaScript that runs in the Site Editor or other administrative screens. Each execution context uses a different WordPress interface, but all of the strings should identify the same theme text domain.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

Internationalization (often shortened to i18n) prepares a theme for translation. A translation team can then create locale-specific catalogs, and WordPress can select the catalog that matches the site language. The practical goal is not merely to translate the front end: labels, notices, controls and previews that your theme adds to the editor must be translatable too.

Choose and declare one text domain

Start with the theme slug. Use a unique, lowercase, kebab-case value such as acme-blocks, and use that exact value in every localization call. WordPress’s theme guidance requires the text domain to match the theme slug; a mismatch prevents otherwise valid strings from being associated with the theme’s language files.

#1 Best Overall
Sale
Compressed Air Duster,130000RPM Super Power Cordless Air Duster,Rechargeable Brushless Blower,3 Gear Adjustable Blower with LED Light,Dust Remover for Computer/House/Outdoor/Car
  • Powerful Turbo Fan:CAGIWIRU Electric Air Duster have reached speed up to 130000RPM,Can efficient remove dust and debris.With LED light and Three Adjustable Speed to meet with different cleaning tasks.
  • With Attached USB C Fasting Charging cable.Charing 3 hours,Enjoy up to 240 minutes of use on the lowest setting, For third speed can use for 25mins.with four charging options to meet with your needs.
  • Wide Application: attached 5 different nozzles,making it suitable for a variety of scenes, such as car,pet, pc, keyboards, and other electronic devices. It also serves for office and home clean duster.
  • Handy Design & Portable:Cordless air duster electric nozzle is Light weight and small size, design and comfortable to hold and space saving, convenient to carry around. You can put it in your room or inside the car without taking up space.
  • Economical &Reusable: Built durable materials with a long-lasting battery,our CAGIWIRU air duster it's a sustainable alternative to disposable air cans.

Add the metadata to style.css

Place the text-domain declaration in the theme header. If you ship catalogs in a directory inside the theme, also declare that directory with Domain Path.

/*
Theme Name: Acme Blocks
Text Domain: acme-blocks
Domain Path: /languages
*/

The folder named by Domain Path is relative to the theme root. In this example, custom catalogs belong in wp-content/themes/acme-blocks/languages/. Keep the directory name and the metadata synchronized; moving files without updating the header is a common reason that PHP translations are not found.

Free tools Windows power users keep installed

One-click scans. No signup required.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

Use the domain consistently

Every call that belongs to the theme should use acme-blocks, not a plugin’s domain, a temporary project name or a translated value. Consistency matters across PHP, JavaScript, POT files, PO files and generated JSON. If you fork a theme, choose a new slug and update the header and every localization call rather than sharing the original domain.

Find every string that users can see

Before wrapping code, inventory the theme’s output. Include visible copy in templates and template parts, headings and instructions in patterns, fallback messages, labels generated by PHP, and strings used by editor scripts. Also check strings assembled conditionally: a message shown only when a query returns no results is still a translatable string.

Location Execution context Required approach
PHP templates, template parts and helpers PHP at render time WordPress PHP i18n functions with the theme text domain
PHP pattern files PHP while the pattern is registered or rendered Call PHP translation functions around authored text
Static pattern or block markup Stored markup without PHP execution Move authored copy into a PHP pattern when a translation hook is needed
Editor or front-end JavaScript Browser-side script @wordpress/i18n, a wp-i18n dependency and script JSON

Do not assume that text visible in the Site Editor is translated by the same mechanism as text rendered by a PHP template. The locale may be identical, while the catalog format and loading path differ.

Internationalize PHP output

Replace hardcoded user-facing text with a translation function at the point where the string is produced. WordPress documents the rule plainly: every string displayed to the user should be wrapped in an i18n function.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

Simple and escaped strings

Use __() when you need the translated value for further processing, and _e() when you are echoing it directly. Choose an escaping variant that matches the destination, such as esc_html__() for text content or esc_attr__() for an HTML attribute.

Rank #2
EVEO® Screen Cleaner Spray Kit (Streak-Free) TV Screen Cleaner for Smart TV, Lcd, LEd, Oled | Computer Screen Cleaner Spray and Wipe Microfiber Cloth - TV, Monitor, Laptop, iPad, Car - 6.7oz 1 Pack
  • Screen Cleaner is Your Screen’s New Bestfriend! - EVEO is proud to present a screen cleaner that’s perfectly suited for your TV. Meet your new screen cleaner, computer screen cleaner, laptop cleaner, iPad cleaner, Macbook,tv cleaner or any other electronic device. Our screen cleaner spray and wipe along with the included plush microfiber cloth, easily removes dust, fingerprints & other smudges on the screen’s surface. Clean effectively for a streak-free screen
  • Gentle on your Screens - Our screen cleaner spray and wipes is compatible to be used even for the most sensitive LCD, LED, CRT, and OLED screens in proper use. Be at ease knowing that this product is compatible with all the major brands: LG, SONY, Samsung, Sharp, iPad, iPhone, Android screens, Kindle, PC monitors - we’ve got you covered! Can be used as LCD screen cleaner, tv cleaner, smart tv screen cleaner, and more
  • Premium Super Soft Plush Microfiber Cloth - Included in this efficient screen cleaning kit. This screen cleaner spray and wipe has our signature plush microfiber cloth specially designed to comply with screens and monitors and leave them streak-free. Has been shown to effectively absorbs stubborn stains, zero streaks, and no fiber shedding. Always use this together with our screen cleaner for the best results
  • Easy-to-Use Screen Cleaner Kit + microfiber cleaning cloth - The EVEO Screen Cleaning Kit will easily be your new favorite tool when it comes to taking care of the things you love most, quick and easy solution for a streak-free screen. Simply screw on the sprayer gun on the screen cleaner bottle. Spray the cleaning liquid onto the microfiber cloth, then wipe the screen until desired cleanliness & shine is achieved.
  • Quality Screen Care Kit Worth Purchasing - Enjoy a convenient Screen Cleaner anytime, anywhere you need it. Your satisfaction is our top priority. We stand behind the quality of our products and that’s why, you shouldn’t be worrying at all. We manufacture the Best Screen Cleaner. and can be used for laptop cleaning kit, laptop screen cleaner, tv screen cleaner for smart tv. MacBook screen cleaner, monitor cleaner or screen cleaner spray for electronic devices with microfiber cleaning cloth
<h2><?php echo esc_html__( 'Latest articles', 'acme-blocks' ); ?></h2>
<label for='email'><?php esc_html_e( 'Email address', 'acme-blocks' ); ?></label>
<input id='email' aria-label='<?php echo esc_attr__( 'Email address', 'acme-blocks' ); ?>'>

Escaping is still required after translation. A translator’s text is data, so send it through the escaping function appropriate for the HTML, attribute, URL or other context in which it will be inserted.

Add context for ambiguous words

Use _x() when the same source word can have different meanings. The context is supplied to translators and becomes part of the catalog key.

<?php echo esc_html_x( 'Home', 'navigation link', 'acme-blocks' ); ?>
<?php echo esc_html_x( 'Home', 'household setting', 'acme-blocks' ); ?>

Even when the English source text is identical, these two contexts can receive different translations. Add context where a short label, noun, verb or technical term could reasonably be interpreted in more than one way.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

Use plural functions for counted messages

Do not concatenate a number with a singular noun and hope that translators can repair the grammar. Use _n() (or an escaped equivalent) with singular and plural forms and pass the count.

<?php
$count = 3;
$message = _n(
    '%s comment',
    '%s comments',
    $count,
    'acme-blocks'
);
echo esc_html( sprintf( $message, number_format_i18n( $count ) ) );
?>

Plural rules vary by language, so translators need both source forms and the numeric value. If a message also needs context, use the contextual plural form rather than inventing separate strings with punctuation.

Keep translatable text extractable

Pass literal source strings to the i18n functions whenever possible. Building a sentence from fragments makes grammar and extraction harder. Keep placeholders such as %s or %d in the translated string, and document what each placeholder represents for translators.

Internationalize JavaScript used by the editor

Editor-side code uses the WordPress JavaScript i18n package, not PHP functions. Import the functions you need from @wordpress/i18n and pass the same text domain used in PHP.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.
Rank #3
Sale
BladeHawks RGB Gaming Mouse Pad Extra Large Extended 31.5x12 Inch-Black | LED mouse pad with 14 lighting modes, covers keyboard & mouse, anti-slip rubber base, waterproof surface, USB powered
  • 【Large size】:Measuring 800 x 300 mm/ 31. 5×12 inches, which is wider and taller than others. Large mouse pad can perfectly fit your keyboard and mouse of any size, and there is also ample space for peripherals such as phones, tablets, etc.
  • 【LED backlight mouse pad】:Blade Hawks RGB mouse pad provides 7 static modes and 7 dynamic modes will give you the options you are looking for. Power-off memory function remembers the last lighting mode you selected. The super glow fiber Chroma will give you a colorful gaming setup that you want.
  • 【Anti-slip rubber base】:Made from Natural rubber, this gaming mousepad will firmly grip your desktop, allowing you to enjoy the ultimate precision in the games you are most passionate about. It also comes with a texture that enhances this ability even further.
  • 【Smooth and waterproof surface】: Micro-textured cloth surface, for extremely precise mouse control and a smooth movement. When liquid splashes on the gaming mouse pad, it forms water droplets and slides down. Will not delay your work or gameplay.
  • 【Plug and play】: This mouse and keyboard pad is powered by USB, plug and play, no driver required. One button control light modes. Press one time to change the lighting mode, press twice to change the brightness, press and hold about 3 seconds turn ON/OFF.
import { __, _x, _n } from '@wordpress/i18n';

const title = __( 'Featured content', 'acme-blocks' );
const contextualLabel = _x( 'Preview', 'button label', 'acme-blocks' );
const summary = _n( '%d item', '%d items', itemCount, 'acme-blocks' );

The script must declare wp-i18n as a dependency so that the WordPress i18n runtime is available before your bundle executes. If the script is registered or enqueued in PHP, include that dependency in the dependency list for the handle.

Load the script catalog with wp_set_script_translations()

WordPress provides wp_set_script_translations() to associate a registered script handle with the theme domain and load the JSON catalog before the script runs. Call it after registering the script and before it is printed.

$handle = 'acme-blocks-editor';
wp_register_script(
    $handle,
    get_theme_file_uri( 'assets/editor.js' ),
    array( 'wp-i18n' ),
    '1.0.0',
    true
);
wp_set_script_translations(
    $handle,
    'acme-blocks',
    get_theme_file_path( 'languages' )
);
wp_enqueue_script( $handle );

The third argument is optional. Supply it when JSON files are self-shipped in a custom directory; the path must point to the directory that contains the generated script catalogs. If you omit the path, WordPress looks in its standard language locations.

Use one registered handle per script whose strings you extract. A translation file generated for a different handle, domain or path will not be selected simply because the source text is identical.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

Make authored pattern text translatable

Patterns are a frequent source of overlooked English copy. Static block markup can describe a layout, but it does not execute PHP translation functions. When a pattern contains authored text that must change with the locale, place the pattern in a PHP pattern file and call the appropriate i18n function there.

<?php
/**
 * Title: Editorial welcome
 * Slug: acme-blocks/editorial-welcome
 * Categories: featured
 */
?>
<!-- wp:paragraph -->
<p><?php echo esc_html__( 'Welcome to our publication.', 'acme-blocks' ); ?></p>
<!-- /wp:paragraph -->

Keep the block comment delimiters and pattern metadata intact. Only the authored text needs to move into the PHP expression. This approach lets extraction tools see the string and lets WordPress select the translation at runtime. It is especially useful for calls to action, instructional copy and placeholder text that should not remain in English.

For text that is intentionally supplied by a site editor, do not translate the editor’s content in the theme. Internationalize the default or instructional text that your theme owns, while leaving user-entered post content to WordPress’s normal content workflow.

Rank #4
Sale
Vaydeer Wrist Rest for Keyboard and Mouse, Computer Ergonomic Wrist Support Pad, Soft Memory Foam Arm Cushion for Desk, Palm Hand Office Laptop Typing
  • 【Softer and More Comfortable】Vaydeer wrist rest has unique diamond pattern, which is the combination of softness and aesthetics. The materials of wrist rest are improved into higher quality memory foam and covered with silky smooth lycra. The computer wrist rest makes you as comfortable and cushiony as like rest your wrists on clouds.
  • 【Ergonomic Wrist Saver】The wrist rests for keyboard and mouse comes with a 17.32×3.15×0.83 inch keyboard wrist pad and a 5.94×3.15×0.83 inch mouse wrist support. Based on ergonomic design, the unique concave shape is the perfect fit for your wrist joints. The wrist rest pad fits most computer keyboards and laptops, improve hand and wrist posture, release your wrist and arm stress.
  • 【Non-Slip Rubber Bottom】Featuring an anti-skid silicone base on the bottom, this wrist keyboard support stays firmly in place on your desk, preventing the padding from sliding around, ensuring stable and consistent wrist support during extended computer sessions.
  • 【Better Experience & Pain Relief】Our keyboard arm rest is beneficial to alleviate the soreness caused by direct contact and friction between your arm and a hard desk surface, reducing the risk of wrist fatigue or carpal tunnel. The soft texture of memory foam can evenly distribute the pressure around your wrists and provide good support with just enough give.
  • 【Helpful in Multiple Scenarios】Whether you're working, studying, writing, typing, gaming, this keyboard and mouse rest combo is an essential accessory to add comfort and support to your hands and wrists. It’s also a great gift for men, women, family, friend, coworker, gamer, teacher, etc.

Extract catalogs with WP-CLI

Extraction creates a source catalog that translators can work from and, for JavaScript, JSON files that the browser can consume.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

Create a POT file

From the project directory, run:

wp i18n make-pot ./ languages/your-theme.pot

The first argument is the directory to scan; the second is the output file. Adjust both paths for your project. The command collects strings from supported PHP and JavaScript sources and records domains, contexts and plural forms. Review the generated POT file to catch missing strings, an unexpected domain or a pattern that was left as static markup.

Translate the catalog and create JavaScript JSON

A translator works from a PO file made from the POT catalog. After the PO files contain translations, convert them to JED 1.x JSON with:

wp i18n make-json languages/ languages/

Use source and destination directories that match your project. The command produces JSON catalogs for JavaScript strings. JavaScript filenames follow WordPress’s documented domain-locale-handle or domain-locale-path-hash naming scheme. The domain, locale and script identity therefore have to agree with the handle and file path used at runtime.

Artifact Purpose Consumed by
POT Template containing extracted source strings Translators or localization workflow
PO Locale-specific source and translated entries Translation workflow and catalog conversion
JSON (JED 1.x) Browser-readable JavaScript translations wp_set_script_translations() and wp-i18n

Regenerate the POT and JSON files whenever strings, contexts, plural forms, domains or script handles change. Treat generated files as build artifacts whose names must not be casually renamed.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Support on Ko-Fi

Choose how translation files are delivered

The WordPress.org language-pack path

Themes distributed through the WordPress theme directory can use language packs. WordPress downloads the appropriate packs into wp-content/languages when the site language and installed theme require them. This keeps translations separate from the theme update and lets WordPress update catalogs independently.

This route still requires correct metadata and domains. Automatic delivery does not fix a Text Domain that differs from the theme slug, nor does it repair a JavaScript file whose handle or naming does not match the generated catalog.

Best Value
Sale
Under Desk Cable Management Tray No Drill, Metal Mesh Cable Management Under Desk with Clamp Mount, 2 Hole Cable Tray with Wire Management and Cord Organizer for Home Office Standing Desk
  • 【No Drill Mounted】Cable management tray can be assembled in as little as 3 minutes or less-simply. Side clips easily clampe the edge of desk, pass through the holes on the sides, and secure excess cables with baskets. Desk cable management supports inward or outward installation to meet your needs in different scenarios, and provides you with great convenience when collecting and organizing wires.
  • 【Rubber Pad Protects Desk】Wire organizer under desk built-in soft rubber pads on the clamp protect your desk from scratches, so you will not damage your furniture or office.
  • 【Sturdy and Beautiful】Cord management under desk is made of high-quality carbon steel and holds about 15 lbs. The wire basket has 2 holes on each side of the tray to enable your cables to pass freely. Cable baskets are suitable for desk thickness use from 0.4" to 2.4".
  • 【Space Saving & Keep Organized】Desk cable management tray holds all your power cords, outlet strips, USB hubs and computer transformers hidden from your feet, and the data cables will not enter the vacuum cleaner to keep your desk clean and tidy. Desk wire organizer is also suitable for use in the kitchen and outdoors.
  • 【Reduce Safety Risks】Cable tray under desk keeps all plugs away from your kids, no more worry about tripping. Using 2 holes wire tray saves extra space, helps you easily cabling and wire protection. The mesh design is not easy to accumulate dust, but avoids safety accidents caused by messy wires.

Self-shipped catalogs

A custom or privately distributed theme can ship catalogs in its own language directory. Declare Domain Path, place the files under that path, and load the PHP text domain from the directory with WordPress’s theme text-domain loading API (commonly load_theme_textdomain()). For JavaScript, pass the same directory as the optional third argument to wp_set_script_translations().

Keep PHP and JavaScript catalogs together only if their naming and loading rules are both satisfied. A valid PHP catalog does not automatically translate editor scripts, and a valid script JSON file does not translate PHP output.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

Test in a real target locale

Translation work is incomplete until the theme is exercised with the site language changed. In the WordPress administration area, open Settings → General, change Site Language to the target locale, save, and then inspect both the public site and the Site Editor.

  1. Open a page that uses each template and template part containing theme-owned text.
  2. Insert or preview every pattern that contains authored copy.
  3. Open editor screens that load the theme’s JavaScript and verify labels, notices and controls.
  4. Exercise singular and plural cases, including zero, one and a larger count where the UI exposes counts.
  5. Check strings with context, especially short words used as both nouns and verbs.
  6. Confirm that HTML remains valid and that translated text is escaped correctly in headings, attributes and other destinations.
  7. Switch back to the default locale and verify that the original source strings still appear when no translation is available.

Test with the same distribution method you will ship. A theme-directory language pack and a self-shipped catalog use different file locations, so success in one arrangement does not prove the other is configured correctly.

Troubleshoot missing translations

Symptom Likely cause What to check
PHP text remains in English Domain mismatch or catalog not loaded Compare the theme slug, Text Domain, function calls and catalog domain; verify the language directory and text-domain loading call.
Only editor JavaScript is untranslated No script catalog, missing dependency or wrong handle Confirm the import from @wordpress/i18n, the wp-i18n dependency, the wp_set_script_translations() call and the generated filename.
One script translates while another does not JSON generated for a different handle or path Regenerate JSON and compare each registered handle and script path with the documented naming scheme.
Pattern copy never appears in the catalog Text is still static markup Move authored text into a PHP pattern and wrap it with an escaping translation function.
Strings exist in POT but not in the locale PO entry is untranslated or stale Open the locale’s PO file, translate the entry, then rerun wp i18n make-json for JavaScript.
Wrong wording appears for a short label Missing context Use _x() or the contextual plural equivalent and provide a meaningful translator-facing description.
Plural sentence is grammatically wrong Singular and plural were concatenated manually Replace the construction with _n() and pass the count as required.
Translations work in one locale but not another Catalog lacks that locale or the locale-specific file is not delivered Check the target locale’s PO/JSON files, naming and delivery path, then retest with that site language selected.

Release checklist

  • The theme slug, Text Domain header and every PHP and JavaScript call use the same lowercase kebab-case domain.
  • Domain Path is declared when catalogs are shipped inside the theme, and the directory exists in the release.
  • User-facing PHP output uses the correct escaped, contextual or plural function.
  • Editor scripts import from @wordpress/i18n and declare wp-i18n as a dependency.
  • Each registered script has translations associated through wp_set_script_translations().
  • Pattern-authored copy that needs translation is in a PHP pattern rather than static-only markup.
  • wp i18n make-pot has been run against the current source tree, and locale files were updated from the resulting catalog.
  • wp i18n make-json has produced JSON with the correct domain, locale and handle or path naming.
  • The release has been tested from the Site Editor and the public site with at least one target locale selected.

Which implementation belongs where?

The shortest reliable decision rule is to match the API to the code that executes the string.

Question Use
Will PHP print or build this value? A PHP i18n function, with escaping appropriate to the output.
Does the meaning change with a count? A plural function such as _n(), not manual concatenation.
Can the same source word mean different things? A contextual function such as _x().
Will a browser-side script display it? @wordpress/i18n, the wp-i18n dependency and a matching JSON catalog.
Is authored text trapped in a static pattern? Move the pattern to PHP so translation functions can run.
Who supplies the catalogs? Use WordPress language packs for directory-hosted distribution, or ship and explicitly load files from the theme’s language directory.

Following those boundaries gives a block theme a predictable translation pipeline: declare one domain, mark every owned string, extract catalogs, load the files that match each execution context, and verify the result in the locale your users will see.

What’s actually slowing this PC down?

Pick the symptom - the matching free tool is one click away.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.