Universally Documentation

Step-by-step guides, multilingual SEO tips, and best practices to help you translate and scale your WordPress website.

Include and Exclude CSS Selectors

CSS selectors give you precise control over which parts of your page are translated. You can target specific sections for translation or exclude sections that should remain untranslated.

These settings are configured in your project’s Settings tab, under Include CSS Selectors and Exclude CSS Selectors. Enter one selector per line.

How It Works

Universally uses CSS selectors to determine which HTML elements contain translatable text. The translation engine processes the page in two phases:

Exclude phase: Elements matching exclude selectors are removed from the translation context entirely. Their content is never seen by the translator.
Include phase: Only text inside elements matching include selectors is extracted for translation.

Exclude selectors are applied first, so they always win over include selectors.

Default Behavior

Without any custom configuration, Universally already translates the most common content elements and excludes non-content elements.

Included by default

Headings: h1, h2, h3, h4, h5, h6
Text: p, blockquote, figcaption, summary
Lists: li, dt, dd
Tables: td, th, tr, thead, tbody, tfoot
Forms: button, label, option
The <title> tag
Elements with the .translate class
Elements with translate="yes" attribute

Excluded by default

<script>, <style>, <noscript> tags
<pre> blocks (code snippets)
Elements with the .notranslate or .no-translate class
Elements with translate="no" attribute
Elements with an hreflang attribute

WordPress sites

For WordPress sites, these additional defaults apply automatically:

Included:

.wp-block-button__link (Gutenberg button blocks)
.menu-item.menu-item-has-children > a (menu items with submenus)

Excluded:

#wpadminbar (admin toolbar)
.wp-admin (admin elements)

Include Selectors

Use include selectors to add elements that are not translated by default. This is useful for custom components or non-standard HTML structures.

Examples

.product-description
#hero-text
[data-translate]
.custom-widget .title
article .excerpt

When to use

Your site uses custom components with classes not in the default list
You have <div> or <span> elements containing translatable text that aren’t inside a default-included element
Third-party widgets render text in non-standard containers

If you can edit your HTML, the easiest way to include an element is to add translate="yes" or class="translate" directly in your source code — no dashboard configuration needed.

<div translate="yes">This will be translated</div>
<div class="translate">This too</div>

Exclude Selectors

Use exclude selectors to prevent specific sections from being translated. Content inside excluded elements is completely ignored.

Examples

.pricing-table
#code-examples
.api-reference
.user-generated-content
[data-no-translate]
footer .copyright

When to use

Code blocks or technical reference sections
User-generated content that should stay in the original language
Pricing or numerical data that shouldn’t be modified
Third-party embeds that handle their own localization
Navigation elements that should remain in the source language
Legal text that must stay in the original language

If you can edit your HTML, the easiest way to exclude an element is to add translate="no" or class="notranslate" directly in your source code — no dashboard configuration needed.

<h1 translate="no">WP Rocket</h1>
<p class="notranslate">This stays in the original language</p>

Selector Syntax

Universally supports standard CSS selector syntax:

Selector	What it matches	Example
`.class`	Elements with a class	`.sidebar`
`#id`	Element with an ID	`#footer`
`[attr]`	Elements with an attribute	`[data-translate]`
`[attr="value"]`	Elements with a specific attribute value	`[role="navigation"]`
`.parent .child`	Nested elements (descendant)	`.blog-post .title`
`.parent > .child`	Direct child elements	`.nav > .item`

Validation rules

Each selector must contain at least one ., #, or [ character
The wildcard * selector is not allowed (it would match everything)
Maximum selector length is 200 characters
Empty lines are ignored

Common Patterns

Translate a custom component

.my-component

Translates all text inside elements with the my-component class.

Exclude a section but translate a part of it

This is not directly supported. Exclude selectors remove elements entirely before include selectors are processed. If you need to translate part of an excluded section, restructure the HTML so the translatable part is outside the excluded container.

Exclude chat widgets

#intercom-container
.drift-widget
.tawk-widget
[id^="hubspot-messages"]

Exclude code documentation

.code-block
.api-endpoint
pre code
.syntax-highlight

Translate custom WordPress blocks

.wp-block-custom .content
.elementor-widget-text .elementor-text-editor
.fl-module-content

Related Settings

Exclude Link Localization — Prevent internal links from being rewritten with language prefixes

Exclude Pages — Skip entire pages from translation based on URL paths

Tips

Use browser DevTools to find selectors. Right-click an element, select “Inspect”, and note the class or ID.
Be specific. .sidebar .widget-title is better than .widget-title if you only want to target sidebar widgets.
Test after changes. Visit a translated page after updating selectors to verify the results.
Use .notranslate in your HTML. If you control the HTML, adding class="notranslate" to an element is often simpler than configuring exclude selectors in the dashboard.
Exclude selectors always win. If the same element matches both an include and exclude selector, it will be excluded.

Was this helpful?