Una fuente, varios idiomas, la misma ruta
Internationalization looks easy while a product still fits on one screen. Extract a few strings, add a language selector, translate the buttons and the job appears finished. That picture collapses once the product contains dozens of games, routes, categories, help screens, statistics, SEO metadata, generated language and long-form editorial content. In September 2026, when the project was still called PuzzleHub, we reached exactly that point: translation was no longer a writing task alone. It had become an architectural constraint.
Today the brand is Blupoli and the puzzle product is Blupoli Puzzles. The editorial pipeline and localized route system have evolved since then. The question that opened the work, however, is still useful: how do you let one person use the same product in several languages without manufacturing a separate copy of the product for every locale? The answer starts by separating identity, logic and presentation.
A game does not become a different game when the language changes
A saved Sudoku should remain the same Sudoku if the player switches from Spanish to English. Its statistics should not split, favourites should not disappear and the session should not become another entity. The same is true for a category, difficulty setting or configuration. Language changes how those things are described, not what they are internally.
That principle sounds obvious until visible text has been used as an identifier. If a translated name is the key, changing language breaks references. If the category “Números” is literally the identity of the category, “Numbers” looks like a different object. Stable IDs solve the problem: logic keeps one identity and localized labels sit above it.
Interface strings are the smallest part of the job
Buttons such as New game, Undo and Help are the comfortable case. They are short, repeated and relatively stable in context. They can live in translation catalogues, be checked for missing keys and selected by active locale. This layer matters, but it does not represent the real complexity of a multilingual platform.
The harder cases are contextual copy, localizable product data, generated language and editorial pieces. A category description is not a label. An Einstein Riddle clue is not a fixed string. A three-thousand-word article should not travel through the same mechanism as a button. Good internationalization starts by accepting that content exists at different scales.
Three scales need three strategies
The first scale is UI: short reusable strings. The second is product data: names, summaries, categories, rules and metadata attached to stable entities. The third is editorial: Blog, Devlog, guides and long-form pieces with their own voice, intent and SEO. Trying to force all three through one translation dictionary makes the system unpleasant for both authors and developers.
Separating them lets each layer carry the right checks. UI can demand key coverage. Product data can validate that every game exposes the fields a locale needs. Editorial content can represent a missing translation honestly rather than publishing a misleading clone under another language. Each layer gets a clear contract.
Routes are part of the product too
A multilingual website needs a public way to represent locale in the URL. Swapping text in the browser is not enough. The address must be stable, linkable and understandable to the build system, search engines and users. Localized routes give each language version a clear public identity.
Blupoli's current pipeline builds localized route trees and applies additional publication rules to editorial content. Automation does not remove the architecture decision; it makes the decision repeatable. Internal links can remain in the intended locale, and the system can recognize when a translation does not exist instead of pretending one does.
The right fallback is not Spanish text under an English URL
One of the most useful decisions in the editorial system is accepting “translation missing” as a legitimate state. If an article exists only in Spanish, automatically generating an English route containing the same Spanish body creates duplicate content and misleads readers and crawlers. It looks like coverage, but it is fictional coverage.
The project's documentation still preserves this behavior: English translations are real files, not automatic copies of Spanish originals. When a translation is absent, the English listing can point to the Spanish source with appropriate context instead of inventing an English page. The newer write-blog contract is stricter and requires ES+EN parity for new or fully rewritten work, but the architecture still knows how to represent legacy gaps correctly.
Canonical and hreflang describe the relationship between versions
A translation is not an isolated page. International SEO needs each locale to declare its canonical URL and expose the equivalent versions of the same content. Reciprocal hreflang links form an explicit relationship between those pages. The point is not decorating the head element; it is preventing languages from competing as duplicates or search results from sending a reader to the wrong version.
That means publication date, author and slug need to stay coherent while title, description and body are genuinely local. It also means inspecting the generated result, because a duplicated prefix or incorrect canonical can turn a good translation into a contradictory SEO signal.
An English page deserves an English title everywhere
Editorial localization does not end when the article body has been translated. The H1, document title, meta description, Open Graph fields, Twitter card, alt text and structured data all belong to the experience. An English article that still generates a Spanish social card tells the reader that localization stopped halfway through the pipeline.
We hit this problem in practice while rebuilding the editorial archive. It led to localized cover generation when an editorial card includes language-specific title text. That is a good example of internationalization exposing a dependency that was easy to miss when there was only one locale. Translation forces the entire publication chain to be examined.
Internal links need to understand locale
An English article that repeatedly sends readers back to Spanish pages breaks the feeling of one coherent product even when every URL technically works. Automation can create a different failure: a localization step adds a prefix to a URL that already contains one and produces paths such as /en/.... That problem is not visible from the prose. It appears in the generated graph of links.
The build therefore includes normalization for localized editorial routes. Authors can focus on the logical destination while the pipeline protects the final route from duplicated prefixes and keeps shared assets from accidentally becoming locale-scoped. Links are part of localization because they preserve linguistic context from one page to the next.
Not every asset should be duplicated per language
An abstract illustration of a board can be shared between Spanish and English if it contains no embedded copy and communicates the same thing in both places. Duplicating it only creates extra files to maintain. An infographic with text baked into the image may need separate versions because the language is part of the visual content.
We increasingly prefer visuals that communicate structure through geometry, relationships and composition, leaving explanatory language in localized alt text and captions. That lets one asset serve several locales without becoming semantically empty. When embedded text is necessary, the pipeline needs to know that localized variants exist.
Alt text is localized content as well
Sharing the same image does not mean sharing the same alt string. Alternative text describes the relevant function or content of the image in the context of a page. Someone reading in English should not encounter a Spanish description simply because the SVG file is shared.
The same applies to captions, labels and accessible names. Accessibility and internationalization are not separate concerns here; both depend on meaning. If visible text changes language but assistive text does not, the page becomes two different experiences layered on top of each other.
Dates and numbers reveal superficial localization quickly
Translating words without adapting formats produces pages that feel assembled rather than native. Month names, separators, day-month ordering, decimals, percentages and units follow local conventions. An article can preserve one publication timestamp while presenting it idiomatically in Spanish and English. The identity of the date is shared; its representation is local.
The same principle belongs in product statistics. Store numbers and timestamps, not already-formatted strings. The UI formats them for the current locale. Changing language then becomes a presentation operation rather than a migration of persisted state.
Pluralization is language logic, not string concatenation
“1 game” and “2 games” look trivial until languages with different plural rules enter the product. Building sentences by concatenating a number with a translated noun fails as soon as grammar becomes more complicated. Internationalization APIs exist because plural categories, ordering and interpolation are real language rules.
The broader lesson is to keep business logic from improvising prose. Engines produce quantities and states; presentation chooses the linguistic form. The same separation that makes generated Einstein clues localizable also helps with something as mundane as a statistics label.
Generated content forces the system to model meaning
Some puzzles barely use words during play. Others generate sentences. The Einstein Riddle engine is a clear example: an adjacency clue should exist as a structured relation and only then be rendered in the active language. If the generator itself emits “A está junto a B,” Spanish has leaked into game logic.
Keeping meaning separate from wording allows another language to be added without rewriting the algorithm. It also makes testing easier: we can verify that the relation is correct independently of its sentence. Internationalization becomes an architecture test rather than a cosmetic feature.
Saving a session should not accidentally save a language
If a saved session stores clues as already-rendered sentences, changing language halfway through a game creates mixed-language state. Persisting the semantic representation lets the UI reconstruct those clues in the current locale. The session remains the same while its presentation changes.
This applies to other persisted data as well. Game IDs, difficulty, categories and actions should be neutral to language. Localization happens when state is presented, not when identity is stored. It is another consequence of treating model and copy as separate responsibilities.
Categories need editorial translation, not only equivalent labels
An enriched category may explain mechanics, cognitive skills and examples. Translating the category name is not enough. The surrounding copy needs to sound natural, remain accurate and use terminology that makes sense in that language. A literal translation can be technically complete and still read awkwardly.
Terminology therefore becomes a product decision. If we choose how to translate candidate, clue, region or constraint, that choice should remain consistent across games, help and articles. Linguistic consistency lowers learning cost in much the same way visual consistency does.
A glossary is product infrastructure
Once the catalogue becomes large, terminology decisions no longer fit reliably in one person's memory. A glossary or documented conventions prevents the same concept from receiving three different names in three games. It also gives reviewers a concrete reference when AI-assisted translation produces plausible but inconsistent wording.
A glossary does not need to freeze language forever. It can evolve. Its value is recording a decision and letting the change propagate deliberately. Without that memory, every translation reopens discussions the project has already solved.
AI accelerates translation without removing editorial review
Agents can produce a complete first pass very quickly, especially when they receive the original, a glossary and product context. That speed is useful, but it introduces a familiar risk: confusing coverage with quality. A translation can include every sentence and still sound mechanical, flatten a nuance or use the wrong puzzle term.
That is why we treat English editorial work as transcreation. Facts, structure and destinations stay aligned where useful, but sentences are rewritten for natural rhythm. The English version then receives its own review for headlines, punctuation, anchor text and search intent. Parity means parity of substance, not syntax.
Localization can break layout too
A button that fits in English may be considerably longer in Spanish, German or French. A heading may wrap. A table may stop fitting. If a component works only with the exact length of its source strings, localization has exposed a design debt.
Responsive design and i18n reinforce each other because both test how dependent the interface is on rigid assumptions. Components that tolerate textual variation are also better prepared for accessibility settings, zoom and unexpected screen sizes.
The language selector is almost the end of the problem
The visible control for switching languages matters, but it represents only a small fraction of the system. Routes, preference persistence, state, fallbacks, links, data, metadata and content all need answers first. A beautiful selector on top of a partially translated experience only makes the inconsistency easier to notice.
We prefer measuring real coverage. Knowing which surfaces are localized and which are not allows the product to expand honestly. The UI can communicate a fallback instead of presenting a mixed-language page without explanation.
The build can turn language rules into quality gates
A declarative architecture allows checks to become automatic: translations retain author and publication date, English routes do not publish Spanish bodies, alternate links are reciprocal, canonicals match locale, assets exist and internal links do not gain duplicate prefixes.
These checks matter because internationalization failures are often silent. The page loads, but SEO metadata is wrong. The link works, but switches language. The article is translated, but the social card is not. A quality gate turns forgettable details into repeatable requirements.
Internationalization forces us to decide what is genuinely shared
Light mode exposes hard-coded colours. A second language exposes hard-coded text, rigid routes and data models that mix identity with presentation. That is why i18n behaves like an architecture audit. Well-separated pieces tend to localize cleanly; coupled pieces require exceptions.
The goal is not zero exceptions. Some cultural content or unusual mechanics will need specific treatment. The goal is for those exceptions to be intentional rather than accidental consequences of a system that silently assumed one language.
International SEO belongs inside the editorial workflow
A title that matches Spanish search intent may not map to the best English phrasing. The meta description should be written naturally. Internal anchors should describe destinations for local readers. Even when two editions share the same argument, each needs its own SEO pass.
This protects us from mechanical keyword translation. The aim is not repeating a phrase in two languages; it is serving equivalent intent. The system can automate technical relationships while editorial review decides how the story should appear in search.
The same story can use a different rhythm in each language
Literal translation tends to preserve sentence length, connectors and argument order even when the second language would prefer another rhythm. An English edition can restructure a transition or choose a different idiom without changing the underlying facts. That freedom is compatible with parity.
What should not drift casually is substance: dates, product state, authorship, important links, uncertainty and distinctions between shipped, tested and planned work. Transcreation adapts voice; it does not rewrite history.
Designing for i18n early stops every new feature from creating more debt
Postponing internationalization can feel efficient while a product is changing quickly. The cost appears later when every component, game and article adds more embedded assumptions that must eventually be extracted. Introducing the constraint early helps new work begin with a separation between logic and presentation.
That does not mean translating absolutely everything on day one. It means the system knows locales exist. A feature can launch with limited coverage while still using stable IDs, translation catalogues and route structures prepared to grow. Architecture prevents translation debt from multiplying unnoticed.
Quality improves when absence is explicit
One counterintuitive principle remains useful: a missing translation can be better than a false translation. If an article has not been properly edited in English, clearly exposing the Spanish original preserves trust. Publishing an unchecked automatic version may satisfy a coverage metric while lowering the experience.
The infrastructure needs to support that honesty. Content can exist in Spanish, be discoverable from the English index with a clear notice, and gain an English route only when a real English edition exists. The stricter write-blog workflow now creates both versions together, but the fallback remains important for older material.
Multilingual QA means testing journeys, not only strings
A translation review can confirm that every sentence exists and still miss a product failure. We also need to walk through navigation, language switching, back navigation, links from Blog to Puzzles, saved sessions, empty states and pages where an equivalent translation has not yet been published. Language changes complete journeys, not just labels.
The strongest QA therefore combines automated invariants with real flows. The build can guarantee metadata relationships and file coverage while a human review can notice whether switching context makes sense. That avoids two bad extremes: relying only on screenshots or relying only on the absence of missing-key errors.
Locale boundaries should not leak into domain behavior
Another useful test is to change language while keeping the same game state and ask what genuinely needs to change. Labels, help, clue wording and formatted dates should update. The generated puzzle, score, seed, solution and statistics identity should not. If a language switch alters domain behavior, presentation has leaked too far inward.
This test is valuable because it turns an abstract architectural principle into a concrete product action. A user changing language should feel as if the same session learned another way to speak, not as if they were transported into a parallel account.
From PuzzleHub to Blupoli, the constraint survived the rebrand
The product name changed, public architecture evolved and the editorial pipeline became much stricter. The underlying decision remained: Blupoli should not multiply its logic every time it adds a language. Engines, IDs and domain state continue to have one source of truth.
What multiplies is presentation: copy, titles, descriptions, public routes and editorial editions adapted for each audience. That is the duplication we want, because it expands cultural accessibility without creating divergent products.
A new language should open another door, not build another house
The metaphor captures the architecture we are aiming for. Every locale needs a real entrance, clear SEO signals and a coherent experience. Behind that entrance should still be the same platform: the same games, the same saved sessions, the same identifiers and the same rules.
When that separation works, adding a language is still serious work — translation, QA, terminology, layout and SEO — but it stops being a rewrite. That is the real goal of good internationalization: increase the reach of the product without fragmenting the engineering that keeps it coherent.