Issues Discovered While Setting Up Development Environment to Apply Noto Sans/Serif Korean on ko.wordpress.org

[Jiwoon-Kim]

Background

To improve typographic consistency and readability on the Korean WordPress.org (ko.wordpress.org) site, there was an initiative to apply Noto Sans/Serif Korean fonts (Noto Sans KR, Noto Serif KR). These fonts are designed for optimal CJK (Chinese, Japanese, Korean) support, unlike the default global fonts (EB Garamond, Inter) that primarily target Latin scripts and lack comprehensive CJK glyph coverage[2].

Technical Challenges in Development Environment

• When integrating Noto Sans/Serif CJK into the WordPress.org theme stack, several technical issues surfaced:
  • Font loading errors: Ensuring that the correct font files (e.g., NotoSerifKR-cjk.woff2) are present and referenced properly in the code. Missing or misnamed files led to PHP warnings and broken typography.
  • Variable definition errors: PHP warnings such as "Undefined variable $font_folder" indicated incomplete or buggy code in font management plugins or theme files.
  • Block registration notices: Errors like "WP_Block_Type_Registry::register was called incorrectly" appeared due to missing namespace prefixes in block type registration, a requirement in modern WordPress block themes.
  • Asset build and mapping complexity: Managing multiple repositories and environments (wporg-main-2022, wporg-parent-2021, wporg-mu-plugins) with Composer, Yarn, and Docker (wp-env) led to dependency conflicts, mapping issues, and confusion about which code was active in each environment.

---

Issues to Report and Suggested Channels

Based on the analysis of your logs, here are the main issues and where you might report them:

---

1. Issue: Persistent PHP Notices Regarding Gutenberg Block Registration (Namespace Missing)

• Observation:
  • PHP notices stating WP_Block_Type_Registry::register was called incorrectly are consistently appearing in environments using themes like wporg-main-2022, wporg-parent-2021, and wporg-mu-plugins.
  • Message: "Block type names must contain a namespace prefix. Example: my-plugin/my-custom-block-type"
  • This might be leading to cascading issues like wp_json_file_decode() (file does not exist) notices and filemtime() (CSS file stat failed) warnings.
• Reproduction Environment:
  • WordPress 6.7.0 or later (as indicated in logs).
  • Local development environment using wp-env.
  • Relevant themes: WordPress/wporg-main-2022, WordPress/wporg-parent-2021 (especially when testing add/korean-font branches).
  • Relevant plugin: WordPress/wporg-mu-plugins (especially add/korean-font or build branches).
• Suspected Cause:
  • Specific Gutenberg blocks within the themes or MU plugin are likely being registered using register_block_type() without a namespace.
• Reporting Channels:
  • GitHub Issues:
    • WordPress/wporg-main-2022 (if observed when this theme is active)
    • WordPress/wporg-parent-2021 (if observed when this theme is active)
    • WordPress/wporg-mu-plugins (if the problematic blocks originate here)
  • Slack:
    • Inquire in #core-dev or #meta to determine the most appropriate repository or if it's a known issue.

2. Issue: PHP Warnings in wporg-mu-plugins related to global-fonts

• Observation:
  • Warnings for undefined PHP variables ($font_folder, $font_file_name) in wporg-mu-plugins/mu-plugins/global-fonts/index.php.
  • A warning "Requested font file cjk.woff2 does not exist" also appears.
• Reproduction Environment:
  • Specific branches of WordPress/wporg-mu-plugins (e.g., build branch as per logs, or potentially add/korean-font due to font file path issues).
• Suspected Cause:
  • Missing variable initialization or incorrect conditional assignment in the font loading logic.
  • Errors in the font file path calculation logic or missing font files.
• Reporting Channels:
  • GitHub Issues: WordPress/wporg-mu-plugins
  • Slack: #meta channel (as it relates to font handling on WordPress.org sites).

3. Issue: Docker Compose version Attribute Warning with @wordpress/env

• Observation:
  • When running yarn wp-env start or yarn setup:wp (which uses wp-env internally), Docker issues a warning that the version attribute in the docker-compose.yml file generated by wp-env is obsolete.
  • Message: the attribute version is obsolete, it will be ignored, please remove it to avoid potential confusion
• Reproduction Environment:
  • Using recent versions of Docker Desktop and wp-env.
• Suspected Cause:
  • The docker-compose.yml template generated by the @wordpress/env package still includes the outdated version attribute.
• Reporting Channels:
  • GitHub Issues: WordPress/gutenberg (as the @wordpress/env package is managed there).
  • Slack: #core-editor or #core-dev channel.

4. (Optional) Observation: Jetpack Translation Loading Timing Notice (Resolved but for reference)

• Observation (Initial Logs):
  • Notice: _load_textdomain_just_in_time was called incorrectly. Translation loading for the jetpack domain was triggered too early.
• Resolution:
  • The issue was resolved by updating the Jetpack plugin to the latest version (13.1.3 => 14.6).
• Reporting Value:
  • A direct bug report might be unnecessary as it's resolved.
  • However, you could share the experience in the Slack #polyglots or #core-dev channel to highlight the usefulness of this new WordPress 6.7.0 notice for developers and remind plugin authors to be mindful of translation loading hooks.

5. (Information Sharing) Experience Testing Korean Font Implementation for wporg-main-2022 and wporg-parent-2021

• Content:
  • Shared your experience setting up a local test environment for Korean font (e.g., Noto Serif KR) implementation, focusing on the add/korean-font branches of wporg-main-2022, wporg-parent-2021, and wporg-mu-plugins.
  • Mentioned using .wp-env.override.json for mapping multiple themes and MU plugins, and configuring a Korean language environment through i18n settings.
  • Confirmed partial font application but noted that persistent PHP notices/warnings (mentioned above) hindered complete testing.
• Sharing Channels:
  • Slack: #meta channel (for WordPress.org site design and functionality) or #polyglots (for Korean user experience).
  • If the add/korean-font branches are associated with specific Pull Requests (PRs) (e.g., https://github.com/WordPress/wporg-parent-2021/pull/174, https://github.com/WordPress/wporg-mu-plugins/pull/685 from your first log file), commenting on those PRs with your test feedback and identified issues would be most direct and valuable.

explain.txt
로그 분석.txt

---

WordPress/wporg-parent-2021#175
@ryelle

[ryelle]

I've converted this to a discussion so we can have a threaded conversation. If there are specific issues that are identified, those can be made in the relevant repos. I'll be replying to the rest of this shortly 🙂

[ryelle]

1. Issue: Persistent PHP Notices Regarding Gutenberg Block Registration (Namespace Missing)

I think WordPress shows this error when the blocks aren't built, too. Can you confirm that you ran the build steps for each project? For example, I think you have all three projects adjacent to one another, so you would need to run:

cd ../wporg-main-2022
yarn workspaces run build
cd ../wporg-parent-2021
yarn workspaces run build
cd ../wporg-mu-plugins
yarn build

Generally you'll want to re-run those for the project you're testing whenever you switch branches.

[ryelle]

3. Issue: Docker Compose version Attribute Warning with @wordpress/env

This is related to the wp-env version. Which project do you see this error on? It should just be a matter of updating the package to @wordpress/env@10.3+.

[ryelle]

4. (Optional) Observation: Jetpack Translation Loading Timing Notice (Resolved but for reference)

It's generally useful to run composer update every so often to make sure you've got the latest plugins, especially now since there are very few active developers working on the code, the lockfiles are not being updated. You can run composer update as often as you want, but we generally don't want PRs that are simply lockfile changes.

Note that the wp-env should be stopped when running composer update, or else it will need a restart.

[ryelle]

5. (Information Sharing) Experience Testing Korean Font Implementation for wporg-main-2022 and wporg-parent-2021

You should also be testing with this PR on wporg-main-2022: WordPress/wporg-main-2022#560.

Looking through your log file, I see that you edited composer.json — that shouldn't be necessary. Creating the .wp-env.override.json should be enough to get the environment to use all the expected files.

I recommend thinking about wporg-main-2022 as the primary testing environment, and only running wp-env there, not in parent or mu-plugins. Here's my setup for reference— I have wporg-main-2022, wporg-parent-2021, and wporg-mu-plugins all checked out next to each other, and my .wp-env.override.json:

{
	"config": {
		"WP_DEVELOPMENT_MODE": "all"
	},
	"themes": [
		"./source/wp-content/themes/wporg",
		"./source/wp-content/themes/wporg-main",
		"./source/wp-content/themes/wporg-main-2022",
		"../wporg-parent-2021/source/wp-content/themes/wporg-parent-2021"
	],
	"mappings": {
		"wp-content/mu-plugins/wporg-mu-plugins": "../wporg-mu-plugins",
		"wp-content/languages": "./source/wp-content/languages"
	}
}

If you want to test other sites, you can use the same process, for example in the Pattern Directory.

[Jiwoon-Kim]

wporg-main-2022 $.wp-env.override.json

{
	"config": {
		"WP_DEBUG": true,
		"SCRIPT_DEBUG": true,
		"WP_DEBUG_LOG": "/tmp/wp-errors.log",
		"FS_METHOD": "direct",
		"WP_ENVIRONMENT_TYPE": "local",
		"JETPACK_DEV_DEBUG": true,
		"WPORG_SANDBOXED": true,
		"WP_MARKET_SHARE": 43,
		"WP_CORE_STABLE_BRANCH": "6.6",
		"WP_CORE_LATEST_RELEASE": "6.6",
		"WP_DEVELOPMENT_MODE": "all"
	},
	"themes": [
		"./source/wp-content/themes/wporg",
		"./source/wp-content/themes/wporg-main",
		"./source/wp-content/themes/wporg-main-2022",
		"../wporg-parent-2021/source/wp-content/themes/wporg-parent-2021"
	],
	"mappings": {
		"env": "./env",
		"wp-content/mu-plugins": "./source/wp-content/mu-plugins",
		"wp-content/mu-plugins/0-sandbox.php": "./env/0-sandbox.php",
		"wp-cli.yml": "./wp-cli.yml",
		"wp-content/mu-plugins/wporg-mu-plugins": "../wporg-mu-plugins",
		"wp-content/languages": "./source/wp-content/languages"
	}
}

[ryelle]

2. Issue: PHP Warnings in wporg-mu-plugins related to global-fonts

I haven't seen this, can you share which language & project you're testing on?

[Jiwoon-Kim]

Hey @ryelle,

I applied the changes exactly as you suggested, and I can confirm everything is now displaying perfectly without any errors. I’m guessing the issue with PHP Warnings in wporg-mu-plugins related to global-fonts was probably because I hadn’t switched to the remove/font-preloading-child branch at the time. I’ve moved to that branch now, rebuilt the workspace, and no more warning messages are appearing.

Since I already have Noto Sans and Noto Serif installed as system fonts, I didn’t notice any major visual differences — though it seems like there’s a slight difference in letter spacing.

I also had a personal question: it seems like the 2022 theme applies FSE styles cleanly, and I was wondering if, rather than dealing with everything through the GitHub code, it might be quicker and easier in some cases to just add custom fonts directly via theme style customizations. I tried adding a font through the theme’s global style and switching it, but it didn’t seem to apply to the global header.

I noticed in the mu-plugins GitHub description it says: “Development of the Global Header and other mu-plugins used on WordPress.org”. Does this mean that font handling for the Global Header is implemented differently from theme-based font management, and requires a separate approach?

Anyway — thank you so much for your help getting Noto Serif working! Now I’m going to move on to applying Noto Sans for the main body text, and once I figure out how to set Noto for the global header as well, it should be perfect.

Appreciate the support as always 🙌

[ryelle]

I’ve moved to that branch now, rebuilt the workspace, and no more warning messages are appearing.

Great!

Since I already have Noto Sans and Noto Serif installed as system fonts, I didn’t notice any major visual differences — though it seems like there’s a slight difference in letter spacing.

Is the difference noticeable? It could either be that you have a different version of the font installed, or something happened when splitting the font.

it seems like the 2022 theme applies FSE styles cleanly, and I was wondering if, rather than dealing with everything through the GitHub code, it might be quicker and easier in some cases to just add custom fonts directly via theme style customizations.

The styles are set in code so that they can be version controlled, and so that we can dynamically switch based on locale. For the main Rosetta sites it's fine, since those are real WordPress sites—you can write a post on ko.wordpress.org. But for others like the directories, ko.wordpress.org/themes is the same site as wordpress.org/themes. So if you change a setting, it will apply to all languages.

I noticed in the mu-plugins GitHub description it says: “Development of the Global Header and other mu-plugins used on WordPress.org”. Does this mean that font handling for the Global Header is implemented differently from theme-based font management, and requires a separate approach?

It should not be. What exactly is the issue you're seeing? I see Noto Serif applied to 한국어 in the global header.

I’m going to move on to applying Noto Sans for the main body text

Oh, I think I missed this request. I only set up Noto Serif. I must have assumed you were okay with the same setup as the Japanese and Chinese locales — they requested Noto Serif for headings and would fall back to system fonts for body text. Adding Noto Sans looks like it would add at least 2.5MB to each page (even with the subsetting), is it worth the extra page weight?

[Jiwoon-Kim]

@ryelle For example, if you check the global header on ja.wordpress.org, you’ll see that EB Garamond is applied.

[Jiwoon-Kim]

My intention is simply to replace the use of EB Garamond and Inter with Noto Serif and Noto Sans. The goal is to improve typographic consistency across East Asian locales, so that Korean, Japanese, and Chinese sites share a unified typographic standard for both headings and body text.

For reference, the file sizes for the Korean variable fonts I’m working with are:

• NotoSerifKR[wght].woff2 — 5,706 KB
• NotoSansKR[wght].woff2 — 3,796 KB

So, combining NotoSansKR and NotoSerifKR would be about 9.3MB.

When you mentioned that adding Noto Sans would increase the size by about 2.5MB, I assume you were referring to subsetting or limiting the range of characters.

Just to confirm — the full NotoSansKR variable font is around 3.8MB, and NotoSerifKR is about 5.7MB (as variable WOFF2 files). I’m guessing you were referring to a subset version of NotoSans when you mentioned 2.5MB — is that correct?

Regarding the 9.3MB increase, this is not loaded every time. The font files are downloaded only the first time a page is visited, and then they are cached, meaning they are not re-downloaded with every page view.

CJK web fonts are inherently large. This is not due to the font file format or technology, but rather the sheer number of glyphs. For example, even though both may be in the WOFF2 format, English fonts are around 50KB, while Korean fonts can range from 3MB to 6MB. CJK fonts, with their large number of glyphs, are larger even in WOFF2 format. Therefore, the best practice is to subset the fonts so that only NotoSerif is used for headings and NotoSans for body text, or to optimize the subset range based on the actual characters being used.

Currently, we're managing performance by mixing system fonts like Inter and EB Garamond with global web fonts. For CJK locales, we apply Noto Serif to the headings and rely on system fonts for the body text. However, to improve design consistency across East Asian sites, the suggestion is to unify this approach further.

---

Android devices come with the Noto fonts pre-installed by default. Specifically, both Noto Sans and Noto Serif are included as system fonts, so there’s no need to download additional font files for these fonts when rendering text.

This means that on Android, if a website uses Noto Sans or Noto Serif, the system will automatically use the built-in fonts without needing to fetch them from the web, which improves performance and reduces page weight.

However, if a specific style or weight is required, like with Noto Serif's variable font or other specialized variations, those may still need to be loaded separately. That said, for most cases, since Android devices already provide these fonts, there’s no need to load them from the web again, offering the benefit of not increasing page load time or font file size.

In short, on Android, the default inclusion of Noto fonts means you won’t typically need to worry about additional font files, though there may still be cases where custom fonts or specific weights need to be loaded.

[ryelle]

For example, if you check the global header on ja.wordpress.org, you’ll see that EB Garamond is applied.

Yes, that should be fixed with one of the changes in WordPress/wporg-parent-2021#173.

When you mentioned that adding Noto Sans would increase the size by about 2.5MB, I assume you were referring to subsetting or limiting the range of characters.

Yes, the change in #686 adds subsetting, which breaks the font into parts with latin characters, hangul syllables, hangul jamo, and hanja, so the result is a smaller file size loaded by the browser.

Regarding the 9.3MB increase, this is not loaded every time. The font files are downloaded only the first time a page is visited, and then they are cached, meaning they are not re-downloaded with every page view.

That's true, but we have a wide audience of people coming to WordPress.org, so we want that initial load to be quick too.