Mayank Tripathi

Creating a New FSE Theme with the Site Editor: Internationalization and Accessibility Best Practices

WordPress has undergone a massive transformation over the past few years, moving towards a block-based approach to theme development. With the introduction of Full Site Editing (FSE), developers can now build themes using the Site Editor directly, eliminating the need for traditional PHP-based templates. This blog will guide you through the process of creating a new theme with the Site Editor, focusing on two essential aspects: Internationalization (i18n) and Accessibility (a11y).

1. Getting Started with a Full Site Editing (FSE) Theme

To create a theme with the Site Editor, you’ll need to focus on block-based theme structure. Unlike classic themes that rely on PHP templates for various parts of the website (header, footer, single posts, etc.), block-based themes utilize the Site Editor’s interface to build and customize the entire site visually. Here’s how to set up your first theme:

1.1 Folder Structure for an FSE Theme

A block-based theme has a minimal structure compared to a traditional theme. The essential files include:

lib/
│
├── style.css
├── theme.json
├── index.php
├── templates/
│   ├── index.html
│   ├── single.html
│   └── archive.html
├── parts/
│   ├── header.html
│   └── footer.html
└── assets/
    └── images/
  • style.css: Contains theme details like the theme name, version, and author.
  • theme.json: Defines global settings for your theme, such as typography, colors, and layout.
  • index.php: A fallback PHP file that WordPress uses to render the site.
  • templates/: Includes the various page templates for your site (e.g., index.html, single.html).
  • parts/: Contains reusable template parts, such as headers and footers.

1.2 Defining Global Styles with theme.json

The theme.json file is central to how your theme looks and feels. It defines your theme’s global styles, block settings, and user customization options. For example:

{
  "version": 3,
  "settings": {
    "color": {
      "palette": [
        {
          "name": "Primary",
          "slug": "primary",
          "color": "#3498db"
        },
        {
          "name": "Secondary",
          "slug": "secondary",
          "color": "#2ecc71"
        }
      ]
    },
    "typography": {
      "fontSizes": [
        {
          "name": "Small",
          "slug": "small",
          "size": "12px"
        },
        {
          "name": "Large",
          "slug": "large",
          "size": "32px"
        }
      ]
    }
  }
}

The Site Editor uses this file to provide users with options when customizing their site, ensuring a consistent look and feel.

1.3 Creating Templates and Template Parts

Templates and template parts are essential for defining the structure of your theme’s pages. For instance:

  • templates/index.html: The template for your homepage.
  • parts/header.html: A reusable block-based header for your theme.

Each file is written in HTML but is composed entirely of WordPress blocks. For example:

<!-- parts/header.html -->
<!-- wp:group {"align":"full"} -->
<div class="wp-block-group alignfull">
  <!-- wp:site-logo /-->
  <!-- wp:site-title /-->
  <!-- wp:navigation /-->
</div>
<!-- /wp:group -->

By building your theme with blocks, users can customize everything using the Site Editor.

2. Internationalization (i18n) in WordPress Themes

Building an international-ready WordPress theme means ensuring that your theme can be easily translated and localized. This involves handling text properly and making it adaptable for different languages and cultures.

2.1 Preparing Your Theme for Translation

WordPress has built-in support for translations through gettext functions. When developing your theme, you should wrap every translatable string in these functions. The most common functions are:

  • __() – returns a translated string.
  • _e() – echoes a translated string.
  • _x() – used when different translations are needed depending on the context.

Example:

<!-- In your theme's header.html -->
<p><?php _e( 'Welcome to My Site', 'lib-theme-domain' ); ?></p>

Here, lib-theme-domain should match the name of your theme to ensure the strings are correctly associated with your theme for translation.

2.2 Using a Text Domain

The text domain acts as an identifier for translations. You need to declare your text domain in the theme’s style.css:

/*
Theme Name: Your Theme
Text Domain: lib-theme-domain
*/

2.3 Generating Translation Files

Once your theme is ready, use tools like Poedit or the command line tool WP-CLI to generate a .pot file. This file contains all the translatable strings from your theme. Here’s how you can generate a .pot file using WP-CLI:

wp i18n make-pot ./path-to-theme ./path-to-theme/languages/lib-theme-domain.pot

You can then distribute the .pot file with your theme, allowing users to translate it into their own language.

2.4 Considerations for RTL (Right-to-Left) Languages

WordPress also supports right-to-left (RTL) languages like Arabic and Hebrew. To ensure your theme works with RTL layouts, include an RTL stylesheet:

/* style-rtl.css */
body {
  direction: rtl;
}

WordPress will automatically load this file when the site is using an RTL language.

3. Accessibility (a11y) in Block Themes

Accessibility is an essential aspect of theme development, ensuring that your theme is usable by everyone, including people with disabilities. The goal is to make your theme perceivable, operable, understandable, and robust across different devices and screen readers.

3.1 Semantic HTML and ARIA Attributes

When building block-based themes, it’s crucial to use semantic HTML and ARIA attributes where necessary. For instance, make sure that interactive elements like buttons and links are properly labeled for screen readers:

<!-- Button with ARIA label -->
<button aria-label="<?php esc_attr_e( 'Open Menu', 'lib-theme-domain' ); ?>">
  <?php _e( 'Menu', 'lib-theme-domain' ); ?>
</button>

3.2 Keyboard Navigation

Ensure that all interactive elements (e.g., buttons, forms, links) are accessible via keyboard navigation. Test your theme by navigating solely with the keyboard (using Tab, Enter, Spacebar, etc.) to confirm that users can access all content without a mouse.

3.3 Color Contrast and Visual Elements

The WCAG (Web Content Accessibility Guidelines) require a contrast ratio of at least 4.5:1 for normal text. You can test the contrast ratio of your colors using online tools like the WebAIM Contrast Checker. Also, avoid using color alone to convey meaning. For instance, combine color with text or icons to signify status:

<!-- Example of using text along with color -->
<p class="status success"><?php _e( 'Success', 'lib-theme-domain' ); ?></p>

3.4 Skip Links

For users navigating via keyboard or screen readers, skip links can provide quick access to the main content, bypassing repetitive blocks (like menus). Adding a skip link at the top of your page can greatly enhance accessibility:

<a href="#main-content" class="skip-link"><?php _e( 'Skip to content', 'lib-theme-domain' ); ?></a>

3.5 Testing for Accessibility

Use tools like WAVE, axe, and Lighthouse to audit your theme for accessibility. Also, consider testing with different screen readers, such as NVDA or VoiceOver, to ensure that all content is properly conveyed to users with visual impairments.

Conclusion

Creating a new WordPress theme with the Site Editor opens up exciting possibilities for developers, allowing for a fully customizable and block-based design experience. By implementing best practices for Internationalization (i18n) and Accessibility (a11y), you can ensure that your theme is usable and accessible to a global audience, regardless of their language or physical abilities. Taking the time to focus on these key areas not only enhances the quality of your theme but also contributes to a more inclusive web.

Thank you for reading through the post… More will be added.

by ~Leaveitblank (Mayank Tripathi)