Modeling a landing page as structured fields

When the same landing page ships in three markets (Vietnam, the Philippines and Indonesia), pages that started out identical slowly drift apart. One market grows a second CTA, another gains an extra paragraph under the headline, and translators lose track of which copy is current. This article explains how to model a page as a set of typed fields instead of a free-form document, and how to get there in practice, from the point of view of both content leads and developers.

Why free-form documents drift

Writing a whole page in a rich-text editor is convenient while you have one market and one language. Once markets and locales multiply, the shape of the page itself can start to differ per locale. When the shape is not consistent, comparing translations, reviewing changes and rendering on the front end all become manual, person-dependent work.

• Translation: someone has to match each source paragraph to its translation by eye, every time.
• Review: changes are buried in the full body, so it is hard to see exactly what changed.
• Rendering: elements the design never planned for (an extra heading or image) slip in and break the layout.
• Reuse: pulling the same copy into an app or an email means digging it out of a block of HTML.

Start from the section, not the page

The starting point is the section, not the whole page. For a home page, split it into design units such as Hero and Why, and give each a small number of typed fields. If keys follow a dotted page.section.field order, like home.hero.headline, both editors and developers can tell at a glance where a value appears.

{
  "home.hero.eyebrow": "International shipping",
  "home.hero.headline": "Ship to 20+ countries with ease",
  "home.hero.subcopy": "Track every order in real time, with clear pricing.",
  "home.hero.ctaLabel": "Get a quote",
  "home.hero.ctaHref": "/contact",
  "home.hero.imageAlt": "Staff packing a parcel",
  "home.whyIntro.title": "Why teams choose us",
  "home.whyIntro.description": "A regional warehouse network and support that answers."
}

The key point is the division of labour: the key carries meaning and the value carries copy. Even if the design changes, home.hero.headline is still the main Hero headline. Conversely, avoid reusing one key for a different meaning, because it confuses both translation and review.

Choose field types and editor guidance

Give every field a type. The type determines the input UI and the validation, so wrong values are caught before they go live. In tixigen you mainly choose between four types:

• Text: short, single-line copy such as headlines and button labels.
• Long text: a sentence or two, such as the description under a headline.
• URL: link targets such as the CTA destination, either a site path or a full URL.
• Media: images such as the Hero image, with alt text kept as a separate text field.

On top of the type, give editors some guidance: where the field appears, what it is for, an example, a length guide and a tone. Simple guides such as 60 characters for a headline, 24 for a CTA label and 160 for a description help every market write copy that fits the design. This guidance is used only in the editor and is never included in the public API response.

Share one structure across markets and locales

Field keys are shared by every market; only the values change per market and locale. The current markets and locales are Vietnam (vi, en), the Philippines (fil, en) and Indonesia (id, en). Because the structure is shared, the front end renders every market with the same components, and editors can more easily see which fields still need translating.

// GET /api/v1/public/pages/ph/home?locale=fil
{
  "fields": {
    "home.hero.headline": "Padaliang mundo, isang tap lang",
    "home.hero.ctaLabel": "Mag-quote"
  }
}

Migrating an existing page

When replacing a live page with fields, it is more realistic to start with the high-impact home page than to migrate everything at once. Working in this order surfaces mismatches between design and content early:

1. 1Inventory the current page with screenshots and draw the section boundaries.
2. 2List only the copy and images that actually change in each section, then assign keys and types.
3. 3Add the location, an example and a length guide to each field.
4. 4Enter the copy in the market's default locale first, then add translations such as en.
5. 5Check the rendering in a signed preview, get it approved in review, then publish.
6. 6Connect the front end to the public API and replace hard-coded copy step by step.

Common pitfalls

• Splitting too finely: breaking one sentence into three fields makes natural translation impossible in languages with different word order. Keep a sentence in one field.
• Putting layout into values: embedding line breaks or colours in copy makes each market look different. Let components decide presentation.
• Renaming keys casually: a key is a contract with the front end. If you must rename, run old and new in parallel and remove the old key after the front end switches.
• Making everything optional: treat essentials such as the headline as required so they never go live empty.

Typed fields take a little more design up front, but the payoff grows with every market and locale you add. Start by carving out just the Hero section of your home page as fields.