Building an English version of my site seemed like a relatively simple task.
In theory, all I had to do was take the content in Portuguese, send it to an AI, and save the result.
In practice, the problem was never just translation.
The problem was doing it without losing editorial control, without breaking the content structure, and without turning internationalization into another fragile layer in the product.
My site already had articles, projects, and content managed through the admin panel in Portuguese. What I wanted was not to manually duplicate everything, nor to maintain two versions of the same content by hand.
I wanted a more sustainable flow:
Portuguese as the source,
English as a derived layer,
and a way to review, adjust, and publish it without improvisation.
That was when the implementation stopped being a simple AI integration and became a more interesting problem of content architecture.
The Mistake Would Be Treating Translation as Replacement
The first important decision was this:
the translation would not replace the original content.
Portuguese would remain the main source.
English would exist as a separate layer, associated with the original content.
In practice, this made it possible to store:
the entity type, such as article or project;
the ID of the source content;
the target language;
the translated fields;
the translation date;
and a reference to the state of the original content at the moment the translation was generated.
This separation significantly improved the quality of the solution.
Because when you treat translation as overwriting, you lose traceability.
When you treat it as its own structure, you gain control.
You can review without deleting the source.
You can evolve without compromising the data model.
And you can think about other languages in the future without duplicating the entire system.
Translating Everything at Once Seemed Efficient. It Wasn't.
In the admin panel, the initial idea was simple: a button that generated the entire English version at once.
It worked well for short content.
But long articles started to expose the real problem.
When title, description, category, and full HTML were sent together, the request became too heavy. In some cases, it came close to or exceeded the practical limit of the operation. In others, it made review harder, because a single bad field compromised the entire generation.
The better solution was not to insist on full automation.
It was to break the flow apart.
I started working with two modes:
1. Fill only empty fields
The system identifies what has not been translated yet and generates only what is missing.
This avoids overwriting content that has already been reviewed.
2. Regenerate by field
Instead of redoing everything, I can regenerate only the title, only the description, or only the content.
This reduced the size of the requests and greatly improved editorial control.
Translation stopped being a magic button.
It became an assisted tool.
And this change matters, because many problems with AI in products come precisely from trying to automate too much of what still requires human judgment.
HTML Was Where the Complexity Really Appeared
The article content is stored as HTML.
And that was where the most sensitive problem emerged.
When translating long content directly, the AI did not change only the text. In some cases, it also changed the structure: it reorganized tags, broke markup, and compromised rendering.
This type of error is dangerous because it does not look like a translation failure.
It looks like a small detail.
But, in practice, it affects the integrity of the content.
To avoid this, I had to create protections around the translation process:
splitting long content into smaller blocks when necessary;
protecting tags and placeholders before sending the content;
translating text without giving the AI control over the structure;
validating the HTML after the response;
rejecting or handling results that changed the expected sequence.
In more sensitive cases, the safest strategy was to operate only on text nodes, preserving the document structure.
This changed the way I understood the problem.
I was not translating “a text.”
I was translating an editorial structure that also carries semantics, layout, and behavior.
Not Every Field Should Be Translated Freely
Another lesson appeared in something that seemed trivial: category.
In an article, the visible category may be “Tecnologia.”
But internally, the system works with keys like tech, career, or design.
When this field was treated as common text, the AI started returning inadequate responses for something that, inside the application, should remain structured.
The fix was to clearly separate two things:
the internal key, which remains stable;
the displayed label, which can be localized according to the language.
This looks like a detail.
It is not.
When you mix editorial content with structural data, automation starts corroding parts of the application that should not be touched.
AI can help a lot with language.
But it needs to operate within clear limits.
Internationalization Does Not End With Content
After translation was working in the admin panel, a more interesting problem appeared on the front end.
The cards in the English listing were correct.
But when clicking on an article, the internal page opened again in Portuguese.
In other words: part of the experience respected the selected language. Part of it did not.
The bug was in the navigation flow and in locale propagation.
The detail page was not correctly receiving the language identified in the route, and some internal links were not preserving the /en prefix.
The fix required explicitly propagating the locale throughout the entire page rendering and ensuring consistency also in:
internal links;
related articles;
return navigation;
content resolution by route.
This reinforced one important thing:
internationalization is not just translating strings.
It means ensuring that the entire experience behaves according to the selected language.
Even Reading Time Had to Become Part of the Logic
Another detail that showed the difference between “it works” and “it is consistent” was the estimated reading time.
In the listing, all articles were appearing with 1 min.
The problem was not in the algorithm itself, but in the data flow:
the listing was not returning the readTime calculated based on the real content;
and there was an old response being served from cache.
The fix was simple in concept, but important for the product:
calculate reading time based on the content of the displayed language;
include that value in the API response;
avoid public cache for data that changes shortly after editing or translation.
This made the site better reflect the real state of each version.
And this type of adjustment is what separates an integrated feature from a feature that is merely attached to the system.
The Result Was Not Automatic Translation. It Was a Multilingual Editorial Flow.
In the end, the work was not just connecting an API and calling it done.
It was designing a system where automatic translation could exist without compromising:
the original content;
manual review;
HTML integrity;
structured data;
localized navigation;
and the consistency of the experience.
Today, Portuguese remains the base.
English can be generated, reviewed, and published with more safety.
And the structure is ready to grow without becoming a patch that is hard to maintain.
This was the most interesting point of the whole process:
the most valuable part of AI did not appear when it translated.
It appeared when it became clear everything that needed to exist around it for that translation to be truly usable in a real product.
In the end, it was not about transforming text.
It was about building a process I could trust.
Because automation is easy.
The hard part is automating without losing judgment.
Share on:
No spam. Only content worth opening.