Internationalization

When a product only ships in one country, writing the on-screen text straight into the code is the fast path. Type "Delete" where the button gets drawn and you're done; build the date by gluing year, month and day together and it renders fine. One set of words, one date format, one layout sized to fit them: all of it correct, and none of it separable. Nothing about this hurts until a second language is needed.

Pagedeck hit that moment during a contract review. A customer in Japan asked whether the interface could run in Japanese, and after a day of digging through the code Theo came back with an estimate of two months. On-screen text was scattered across more than four hundred places, and dates were assembled as strings by the code itself, so changing the format meant finding every one of those spots by hand. The contract slipped a quarter.

Finding the text to translate wasn't the only problem. German often runs about 30 percent longer than English for the same meaning, and Pagedeck's buttons had fixed widths set to fit the original words. Text got clipped the moment it went in.

Internationalization is the decision to do this work at the start instead of later. It isn't the act of adding languages — it's the act of building the place languages can go. People shorten it to i18n, counting the eighteen letters between the first and the last.

Every piece of on-screen text moves into language files outside the code, and dates, numbers and currency get handed to regional settings instead of being assembled by the code.

1. Separating the text. The code keeps only a name like button.delete, and the words attached to that name live in a file per language. The English file holds "Delete" and the German file holds "Löschen." Adding a language becomes adding a file.
2. No sentence assembly. Gluing "Document" and " was deleted" together in code falls apart in languages that order those parts differently. Keep the whole sentence in one string and punch a hole where the variable goes.
3. Counts and plurals. English splits one from many, some languages don't split at all, and others have three forms. Write those rules yourself and you rewrite them with every new language, so hand the job to a formatting library.
4. Formats come from settings. One place writes a date year-month-day, another writes it day-month-year, and the symbols that separate thousands from decimals are reversed between countries. Pass a date value to the code and let the regional setting decide how it appears. The same applies to currency symbols and to where they sit relative to the number.
5. Room to grow. Lay out screens assuming the text will get longer. Set a minimum button width instead of a fixed one, and let a label wrap to two lines without pushing everything below it out of place. If the product already does responsive design, where layout adapts to screen size, this applies the same thinking to text length.

The structure pays off in a single language too. With text outside the code, whoever writes the microcopy — the short strings on buttons and hints — can change it without going through an engineer, and fixing one typo no longer waits for a deploy window.

The term comes up when new screens get built, when deferred cleanup gets paid down, and when a new market is on the table.

For new screens it lands at the component level — the reusable unit of code a screen is built from. Build the button component that takes a button label so it grows with the text, and every screen made afterward is safe by default. Fix its width instead and the same bug gets fixed once per screen.

In a product that already exists, this shows up as technical debt, the accumulated cost of cleanup postponed in order to move fast. Skipped internationalization is a textbook case, and the bill grows with the delay because the scattered spots multiply. A week of work in a ten-screen product is a quarter-long project in a two-hundred-screen one.

Verification belongs to quality assurance (QA). It can happen before any translation arrives, using a fake language file. Replace every string with placeholder characters 1.4 times the original length, walk through the screens once, and two kinds of problem show up at the same time: the buttons that clip, and the strings that didn't change at all because they're still written into the source.

"This string is hardcoded. Can you move it into the language file?"

A spot translation can't reach, so the structure needs fixing before anything else.

"Internationalization is done, only the translation is missing. We just fill in the file."

The structural work is finished, so adding a language needs no engineering.

"This button clips in German. Let's drop the fixed width and set a minimum instead."

The text came out of the code, but the layout still can't absorb a change in length.

The quarter after losing that Japanese customer, Pagedeck spent two months moving every string into language files. Since then Noa drops the longest-language version of each string into mockups, and Theo sends back any code review with text written directly into a screen.

The second language actually shipped six months later. That took two weeks, most of it translation and review. The gap between the first two months and the later two weeks is what internationalization buys.

The most common move is skipping it because the product only sells domestically. There's no foreign-language release planned, so the work looks like effort with no payoff, and that reading isn't wrong on its face. What it misses is that the value doesn't come only from translation. Once text lives outside the code, editing text detaches from the engineering schedule, and a typo stops taking days to fix. The people who decide what a button should say get to change what it says. The later cost also keeps climbing — do it after the screen count grows and the same work costs several times as much.

Treating it as a one-time job is the other mistake. Calling it structural work makes it sound like something you finish, which is an easy assumption. In practice every new screen has to follow the same rules, and one string written directly into the code leaves exactly that screen untranslated. Holes like that usually surface not when the translation is commissioned but when a customer in that language opens the screen.