A Developer’s Reminder: The Crucial Role of String Normalization

Lessons from the macOS Unicode chaos and bridging the cross-platform gap with a 1-second CLI tool.

unicode normalization (by chatgpt)

If you are a developer using a Mac as your daily driver, you’ve likely experienced this deeply unfair moment: A file name or a Git commit message that looked perfectly fine on your MacBook suddenly shatters into separated consonants and vowels — like “ㅎㅏㄴㄱㅡㄹ.txt” (instead of “한글.txt”) — the moment it’s shared with your team.

Your teammates will usually ask, “Why do Macs always break text?”

From the Mac user’s perspective, this is incredibly frustrating. If it looks perfectly fine on your screen but breaks when opened in another program, is it really fair to unconditionally blame the Mac?

Today, we are going to dig into the truth behind Unicode normalization (NFC vs. NFD) that causes this “character separation” phenomenon, and explore why string normalization is a fundamental step we often forget in software development.

1. It’s Not a Bug, It’s the ‘Most Perfect Design’ (Apple’s NFD)

Let’s get one thing straight: the fact that macOS breaks text down into separated base characters is not a “bug” caused by Apple mishandling Unicode. Rather, it is the result of Apple’s extreme perfectionism to process text data in the most logical and consistent way possible.

There are two main ways Unicode handles character normalization:

• NFC (Normalization Form Canonical Composition): Assigns a pre-composed, single code block to a character (e.g., ‘한’, or ‘é’). This is the standard for the Web and most other operating systems.
• NFD (Normalization Form Canonical Decomposition): Breaks the character down into its base components (e.g., ‘ㅎ+ㅏ+ㄴ’, or ‘e’ + ‘´’). This is the macOS standard.

The reason Apple forces NFD at the file system level (APFS) is clear: to guarantee absolute consistency in file name searching and comparison. By forcing every incoming string to be broken down into its smallest atomic units (NFD), the probability of data collision within the system converges to zero. Furthermore, from a software engineering perspective, this mathematical, compositional approach perfectly aligns with how combinable writing systems — like the Korean Hangul alphabet or European diacritics — were originally designed to work.

2. The Real Problem: An Ecosystem of ‘Inflexible Applications’

So, Apple’s system is internally flawless. Why does it become a disaster the moment the file leaves the ecosystem? People often lazily generalize this as a “Windows compatibility issue,” but technically, the real culprit is the way countless cross-platform applications handle Unicode.

The vast majority of the world’s systems and W3C Web standards have adopted NFC (Composition) as the standard, primarily to save data capacity and maintain legacy compatibility.

Knowing this, how should an application (like a messenger, a ZIP utility, or a Git client) behave? When it receives an NFD-formatted string, it should ideally have the flexibility to say: “Ah, this is decomposed (NFD) data from macOS. I need to reassemble (Normalize) it to NFC before rendering it on the screen!”

However, an overwhelming number of applications and legacy systems completely lack this “defensive logic” for macOS environments. They simply take the raw, decomposed data coming over the network and render it exactly as is — shattered pieces and all.

Ultimately, it is the collaboration between Apple’s uncompromising principles and the laziness of applications that fail to normalize incoming data that causes our ongoing suffering.

3. Building My Own Solution: 1-Second NFC Conversion

We can’t afford to wait for every application developer in the world to release an update accommodating the Mac’s NFD environment.

The breaking point for me was Git. When collaborating with Windows developers, I realized that Git clients completely ignore the NFD issue. Every time I migrated to a new Mac or updated my global user.name, I had to frantically Google how to fix my shattered name before my Windows teammates noticed.

Tired of searching for the same repetitive workarounds every time I changed my device, I decided to build a permanent solution. That’s why I developed **@nkcroft/unorm**—a lightweight terminal CLI tool that instantly converts this frustrating NFD data into NFC.

test unicode string(by @nkcroft/unorm)

👉 Fix Your Shattered Git Username in 1 Second

If you set up a new Mac, pushed a commit, and realized your name looks like a broken mess (“ㅎㅗㅇㄱㅣㄹㄷㅗㅇ”) on GitHub, you no longer need to manually edit config files. You can fix it permanently with this single line:

npx @nkcroft/unorm@latest --fix-git-user

This command detects if your Git name is incorrectly saved in NFD, automatically normalizes it to NFC (which all programs and the Web can read comfortably), and updates your system config.

👉 Convert Text and Logs via Pipelines

Install it globally via npm (npm i -g @nkcroft/unorm), and easily wash your macOS-generated text files through a pipe before handing them over to your team.

# Install it globally via npm
npm i -g @nkcroft/unorm

# Convert Text and Logs via Pipelines
cat mac_nfd_data.txt | unorm -f NFC > clean_nfc_data.txt

4. Conclusion

The shattered text phenomenon on Macs is by no means a Mac defect. It is merely the shrapnel created by the collision between Apple’s blind faith in logical integrity and an application ecosystem that fails to flexibly embrace it.

However, in a practical collaborative environment, we cannot ignore the universal standard (NFC) used by the majority. The next time a coworker complains about your broken file names, don’t panic. Just calmly run @nkcroft/unorm, hand them the clean, normalized result, and be the cool Mac user who effortlessly bridges the gap!

• 📦 NPM: https://www.npmjs.com/package/@nkcroft/unorm
• 🐙 GitHub: https://github.com/nkcroft/unorm