classic-theme-i18n-textdomain

Classic Theme Internationalization and Text Domain

Use this when adding or reviewing translation readiness in a classic PHP theme: text domain headers, PHP strings, plural strings, context, translator comments, local .mo files, and JavaScript translations.

When to Use This Skill

• Creating or reviewing a theme style.css header.
• Adding visible text to templates, functions.php, Customizer controls, menus, widgets, or comments.
• Loading bundled theme translations.
• Fixing WP 6.7+ "translations loaded too early" notices.
• Auditing text domains before release.

Text Domain Header

Set the text domain in style.css.

/*
Theme Name: My Theme
Text Domain: my-theme
Domain Path: /languages
*/

Rules:

• The text domain should match the theme slug.
• Use lowercase kebab-case, not underscores.
• Use the same literal domain in every translation call.
• Domain Path is relative to the theme root and starts with /.
• Use /languages unless the project has a clear reason for another directory.

Loading Translations

For themes distributed through WordPress.org language packs, WordPress can load translations from wp-content/languages/themes/.

If the theme bundles its own translations, register the path on after_setup_theme.

add_action( 'after_setup_theme', 'mytheme_load_textdomain' );

function mytheme_load_textdomain() {
	load_theme_textdomain(
		'my-theme',
		get_template_directory() . '/languages'
	);
}

For a child theme:

add_action( 'after_setup_theme', 'mytheme_child_load_textdomain' );

function mytheme_child_load_textdomain() {
	load_child_theme_textdomain(
		'my-theme',
		get_stylesheet_directory() . '/languages'
	);
}

Rules:

• Load theme translations no earlier than after_setup_theme.
• Do not translate strings at file load time before after_setup_theme.
• WP 6.7+ warns when just-in-time translation loading is triggered too early.
• Theme-bundled .mo files are named by locale, for example de_DE.mo.
• Language-pack .mo files under wp-content/languages/themes/ are named my-theme-de_DE.mo.