I work on the cultural web project mentioned later in this article. This post focuses on a general engineering approach rather than presenting an independent product review.

Interactive web experiences are often designed from the JavaScript component inward.

The first implementation might begin with state:

type Stage =
  | "idle"
  | "loading"
  | "revealed"
  | "error";

Then come event handlers, animations, API calls, loading indicators, and transitions.

Only later does someone ask:

What happens if the JavaScript bundle does not load?

For many applications, the answer is that nothing happens. The visitor sees a button that looks interactive but cannot perform its primary action.

JavaScript can fail for many ordinary reasons:

• A slow or unstable mobile connection

• A cached HTML file referencing an outdated bundle

• A browser extension blocking a script

• A content-security-policy error

• A deployment containing mismatched assets

• A runtime exception in unrelated code

• A low-powered device taking too long to execute the bundle

Progressive enhancement begins with a different question:

What is the smallest version of this experience that can work with HTML and an HTTP request?

Once that version works, JavaScript can improve its speed and presentation without becoming its only path to completion.

Begin with a normal HTML form

Consider a small web experience that lets a visitor choose a situation and draw a result.

The baseline interface can be a form:

<form method="post" action="/draw">
  <fieldset>
    <legend>Choose a situation</legend>

    <label>
      <input
        type="radio"
        name="situation"
        value="general"
        checked
      />
      General
    </label>

    <label>
      <input
        type="radio"
        name="situation"
        value="new-encounter"
      />
      A new encounter
    </label>

    <label>
      <input
        type="radio"
        name="situation"
        value="waiting"
      />
      Waiting for a reply
    </label>
  </fieldset>

  <button type="submit">
    Draw a result
  </button>
</form>

This form already provides several important behaviors:

• It is keyboard accessible.

• It has a clear submission action.

• It works without a pointer device.

• The selected value is represented by a native control.

• The browser can submit it without JavaScript.

• Assistive technologies understand its structure.

There is no need to simulate radio buttons with clickable <div> elements.

Native HTML gives us a strong starting point.

Validate the request on the server

Client-side validation can improve feedback, but the server remains responsible for accepting only supported values.

const allowedSituations = new Set([
  "general",
  "new-encounter",
  "waiting"
]);

function parseSituation(
  value: unknown
): string {
  if (
    typeof value !== "string" ||
    !allowedSituations.has(value)
  ) {
    return "general";
  }

  return value;
}

The server can select an eligible result:

function drawResult(
  situation: string
): FortuneResult {
  const eligible = results.filter(
    (result) =>
      result.situations.includes(situation) ||
      result.situations.includes("general")
  );

  if (eligible.length === 0) {
    throw new Error(
      "No eligible results are available"
    );
  }

  const index = crypto.randomInt(
    eligible.length
  );

  return eligible[index];
}

A simplified route might look like this:

app.post("/draw", async (request, response) => {
  const situation = parseSituation(
    request.body.situation
  );

  const result = drawResult(situation);

  response
    .setHeader("Cache-Control", "no-store")
    .render("result-page", {
      situation,
      result
    });
});

The response is a complete HTML page containing the selected result.

No JavaScript is required to reach it.

Render a complete result page

The result should remain meaningful without animation or client-side state.

<main id="main-content">
  <article aria-labelledby="result-title">
    <p>Your result</p>

    <h1 id="result-title">
      A Gentle Turning Point
    </h1>

    <p>
      A small change in perspective may
      reveal a path that was difficult to see.
    </p>

    <section aria-labelledby="next-step-title">
      <h2 id="next-step-title">
        A small next step
      </h2>

      <p>
        Give the situation space before
        deciding what it means.
      </p>
    </section>
  </article>

  <a href="/">
    Return to the beginning
  </a>
</main>

This is the core experience.

JavaScript should not be responsible for reconstructing essential content that the server can provide directly.

Enhancement should preserve the form

Once the baseline works, JavaScript can intercept the submission and request only a result fragment.

The form remains in the HTML:

<form
  method="post"
  action="/draw"
  data-enhance="draw"
>
  <!-- Native form controls -->

  <button type="submit">
    Draw a result
  </button>
</form>

<section
  id="result-region"
  aria-live="polite"
  aria-busy="false"
></section>

If JavaScript loads successfully, it can attach an event listener.

const form =
  document.querySelector<HTMLFormElement>(
    '[data-enhance="draw"]'
  );

const resultRegion =
  document.querySelector<HTMLElement>(
    "#result-region"
  );

The script should first confirm that the required elements and APIs exist.

if (
  form &&
  resultRegion &&
  "fetch" in window &&
  "FormData" in window
) {
  enhanceDrawForm(form, resultRegion);
}

If any requirement is missing, the script does nothing. The browser continues using the normal form submission.

That is a graceful failure.

Request a server-rendered fragment

The enhanced flow can send the same form data using fetch.

async function requestResult(
  form: HTMLFormElement,
  signal: AbortSignal
): Promise<string> {
  const response = await fetch(form.action, {
    method: form.method,
    body: new FormData(form),
    headers: {
      "X-Requested-Fragment": "fortune-result"
    },
    signal
  });

  if (!response.ok) {
    throw new Error(
      `Request failed with ${response.status}`
    );
  }

  return response.text();
}

The server can detect the fragment request:

const wantsFragment =
  request.get("X-Requested-Fragment") ===
  "fortune-result";

Then render either the result component or the complete page:

if (wantsFragment) {
  return response.render(
    "partials/fortune-result",
    { result }
  );
}

return response.render(
  "result-page",
  { result }
);

Both responses use the same result data and the same server-side template.

This prevents the normal and enhanced experiences from drifting into two separate implementations.

Manage the loading state without hiding the form

The enhanced handler can temporarily disable the submit button:

function enhanceDrawForm(
  form: HTMLFormElement,
  resultRegion: HTMLElement
): void {
  const submitButton =
    form.querySelector<HTMLButtonElement>(
      'button[type="submit"]'
    );

  if (!submitButton) {
    return;
  }

  form.addEventListener(
    "submit",
    async (event) => {
      event.preventDefault();

      submitButton.disabled = true;
      resultRegion.setAttribute(
        "aria-busy",
        "true"
      );

      try {
        const html = await requestResult(
          form,
          new AbortController().signal
        );

        resultRegion.innerHTML = html;
        focusResult(resultRegion);
      } catch {
        renderError(resultRegion);
      } finally {
        submitButton.disabled = false;
        resultRegion.setAttribute(
          "aria-busy",
          "false"
        );
      }
    }
  );
}

Disabling the button prevents accidental double submissions while the request is active.

It must be re-enabled in finally, including when the request fails.

A permanently disabled primary action is a common failure mode in interactive interfaces.

Move focus deliberately

When a full page loads, the browser and assistive technologies receive a new document.

When only part of a page changes, keyboard and screen-reader users may not know where the result appeared.

The result heading can be focusable:

<h2
  data-result-heading
  tabindex="-1"
>
  A Gentle Turning Point
</h2>

After inserting the fragment:

function focusResult(
  region: HTMLElement
): void {
  const heading =
    region.querySelector<HTMLElement>(
      "[data-result-heading]"
    );

  heading?.focus();
}

tabindex="-1" allows programmatic focus without adding the heading to the normal tab sequence.

The aria-live="polite" result region provides an additional announcement mechanism, but it should not replace clear focus management.

Treat animation as an enhancement

A short reveal animation can create anticipation. It should not become a timer that prevents access to the result.

[data-result-card] {
  animation:
    reveal-result 500ms ease-out both;
}

@keyframes reveal-result {
  from {
    opacity: 0;
    transform: translateY(0.5rem);
  }

  to {
    opacity: 1;
    transform: translateY(0);
  }
}

Visitors who prefer reduced motion should receive the result without movement:

@media (prefers-reduced-motion: reduce) {
  [data-result-card] {
    animation: none;
  }
}

Do not delay the HTML insertion merely to ensure that every visitor watches the complete animation.

The result is the content. The animation is presentation.

Provide a useful failure state

An enhanced request can fail even though the standard page would work.

The error message should provide a recovery path:

function renderError(
  region: HTMLElement
): void {
  region.innerHTML = `
    <div role="alert">
      <p>
        The result could not be loaded.
      </p>

      <p>
        Please try again, or continue using
        the standard page.
      </p>
    </div>
  `;
}

A more complete implementation can include a button that disables enhancement for the next submission:

let enhancementEnabled = true;

form.addEventListener("submit", (event) => {
  if (!enhancementEnabled) {
    return;
  }

  event.preventDefault();
  // Enhanced request
});

After an enhanced failure, a recovery control can set:

enhancementEnabled = false;

The visitor’s next submission then follows the form’s original browser behavior.

This is safer than repeatedly retrying a broken JavaScript request.

Avoid collecting the visitor’s private question

Progressive enhancement also helps clarify the data boundary.

The form may need a broad situation category:

waiting

It does not need:

I sent a private message to a specific person
at 11:42 PM and they have not replied.

The visitor can keep the detailed question in their own mind.

The server receives only the minimum category required to choose eligible content.

type DrawRequest = {
  situation: "general" |
    "new-encounter" |
    "waiting";
};

A technically enhanced experience should not automatically become a more invasive one.

Do not make analytics part of completion

If analytics fails, the draw should still complete.

Avoid this:

await analytics.track(
  "draw_started"
);

const html = await requestResult(
  form,
  signal
);

If the analytics request stalls or throws an exception, the primary interaction may never run.

Analytics should be isolated:

void trackSafely("draw_started");

const html = await requestResult(
  form,
  signal
);

async function trackSafely(
  eventName: string
): Promise<void> {
  try {
    await analytics.track(eventName);
  } catch {
    // Analytics must not block the product.
  }
}

Measurement is secondary to the visitor’s task.

Test both paths

A progressively enhanced application has at least two valid modes.

JavaScript disabled

Test that:

• The form can be submitted.

• The selected value reaches the server.

• A complete result page is returned.

• Validation errors remain understandable.

• The visitor can return to the beginning.

JavaScript enabled

Test that:

• The form is intercepted only when supported.

• The submit button is disabled during the request.

• Only one result is inserted.

• Focus moves to the result heading.

• The button is re-enabled after failure.

• Reduced-motion preferences are respected.

• A failed enhanced request has a standard fallback.

The JavaScript-disabled test should be part of the normal test suite, not a manual check performed once during launch.

With Playwright, a browser context can be created with JavaScript disabled:

const context =
  await browser.newContext({
    javaScriptEnabled: false
  });

const page = await context.newPage();

await page.goto("/");

await page.getByRole(
  "button",
  { name: "Draw a result" }
).click();

await expect(
  page.getByRole("heading", {
    name: "Your result"
  })
).toBeVisible();

This protects the baseline experience from future regressions.

Applying the pattern to a cultural web product

I have been considering these principles while working on Ichizenn’s 恋みくじ, a Japanese love-fortune web experience.

A product like 恋みくじ benefits from animation and anticipation, but its meaning should not depend entirely on those effects.

The essential journey remains simple:

1. Consider a question privately.

2. Choose an appropriate situation.

3. Draw a result.

4. Read and reflect on it.

That journey can exist in ordinary HTML. JavaScript can make the transition smoother without owning the entire experience.

A practical implementation order

For a new interactive feature, I would build in this order:

1. Write the semantic HTML form.

2. Implement server-side validation.

3. Return a complete HTML result page.

4. Test the experience without JavaScript.

5. Extract a reusable server-rendered result fragment.

6. Add the enhanced fetch request.

7. Add loading and error states.

8. Add focus management.

9. Add optional animation.

10. Test both modes in continuous integration.

This order keeps the essential interaction available throughout development.

Final thoughts

Progressive enhancement is not a rejection of JavaScript.

It is a way of assigning JavaScript the right responsibility.

HTML describes the task. The server provides the result. JavaScript improves the transition. CSS improves the presentation.

When each layer has a clear role, the experience becomes more resilient.

Visitors receive a working product when everything loads—and a working product when one layer does not.

What interactive feature in your current project could begin as a normal HTML form before becoming a JavaScript component?

Adding another language to a web application often begins with two JSON files:

text locales/ ├── en.json └── ja.json

The English file contains the original interface:

json { "drawButton": "Draw your fortune", "resultTitle": "Your result", "shareButton": "Share" }

The Japanese file contains the translation:

json { "drawButton": "恋みくじを引く", "resultTitle": "結果", "shareButton": "シェアする" }

This looks manageable until the application grows.

New keys are added to one locale but not another. A translator removes a placeholder accidentally. An English sentence is copied into the Japanese file. A button translation becomes too long for its component. A phrase that sounds harmless in one language becomes an inappropriate promise in another.

A translation can be valid JSON and still be invalid product content.

The solution is to treat localization files as testable application data.

Define one source locale

Choose one locale as the structural reference.

const sourceLocale = "en";
const supportedLocales = ["en", "ja"] as const;

This does not mean that English is culturally more important. It simply gives the build process a stable reference for determining which keys should exist.

type Locale = typeof supportedLocales[number];

Every production locale should contain the keys required by the source locale.

Flatten nested translation objects

Localization files are often nested:

{
  "fortune": {
    "draw": "Draw",
    "result": {
      "title": "Your result",
      "description": "A small step may reveal a new path."
    }
  }
}

Flattening the object makes comparison easier:

type TranslationObject = {
  [key: string]: string | TranslationObject;
};

function flattenTranslations(
  input: TranslationObject,
  prefix = ""
): Record<string, string> {
  const output: Record<string, string> = {};

  for (const [key, value] of Object.entries(input)) {
    const fullKey = prefix ? `${prefix}.${key}` : key;

    if (typeof value === "string") {
      output[fullKey] = value;
    } else {
      Object.assign(
        output,
        flattenTranslations(value, fullKey)
      );
    }
  }

  return output;
}

The previous object becomes:

{
  "fortune.draw": "Draw",
  "fortune.result.title": "Your result",
  "fortune.result.description":
    "A small step may reveal a new path."
}

Detect missing keys

The first validation compares the available keys.

function findMissingKeys(
  source: Record<string, string>,
  target: Record<string, string>
): string[] {
  return Object.keys(source).filter(
    (key) => !(key in target)
  );
}

It can be used during the build:

const missingJapaneseKeys = findMissingKeys(
  flattenTranslations(en),
  flattenTranslations(ja)
);

if (missingJapaneseKeys.length > 0) {
  throw new Error(
    `Missing Japanese translations:\n` +
    missingJapaneseKeys.join("\n")
  );
}

This prevents an incomplete locale from silently falling back to English in production.

The reverse comparison can detect obsolete keys:

function findUnexpectedKeys(
  source: Record<string, string>,
  target: Record<string, string>
): string[] {
  return Object.keys(target).filter(
    (key) => !(key in source)
  );
}

Unexpected keys are not always errors, but they may indicate that an old translation was left behind after a feature changed.

Validate placeholders

Translations frequently contain dynamic values:

{
  "welcome": "Welcome, {name}",
  "resultCount": "You have {count} saved results"
}

A translator may accidentally remove or rename a placeholder:

{
  "welcome": "ようこそ",
  "resultCount": "{total}件の結果があります"
}

The application expects {name} and {count}, but the translated content provides neither.

We can extract placeholders:

function extractPlaceholders(
  value: string
): string[] {
  return [
    ...value.matchAll(/\{([a-zA-Z0-9_]+)\}/g)
  ]
    .map((match) => match[1])
    .sort();
}

Then compare them:

function placeholdersMatch(
  source: string,
  target: string
): boolean {
  return JSON.stringify(
    extractPlaceholders(source)
  ) === JSON.stringify(
    extractPlaceholders(target)
  );
}

The build should report the exact key:

if (!placeholdersMatch(sourceValue, targetValue)) {
  errors.push(
    `${locale}:${key} has different placeholders`
  );
}

This catches a common class of runtime errors before the interface is opened.

Detect untranslated content carefully

An identical source and target value can indicate missing translation:

if (
  locale !== sourceLocale &&
  sourceValue === targetValue
) {
  warnings.push(
    `${locale}:${key} may be untranslated`
  );
}

This should usually be a warning, not a build failure.

Some terms are intentionally identical:

• JavaScript

• TypeScript

• API

• URL

• Product names

• Version numbers

An allowlist prevents unnecessary warnings:

const identicalValuesAllowed = new Set([
  "JavaScript",
  "TypeScript",
  "API",
  "URL"
]);

Automated checks should support editorial judgment, not replace it.

Add content safety rules

A culturally sensitive application may need rules beyond ordinary translation completeness.

For example, a reflective product should avoid presenting entertainment content as certainty.

const restrictedClaims = [
  "guaranteed",
  "will definitely",
  "100% accurate",
  "cannot fail"
];

function findRestrictedClaims(
  value: string
): string[] {
  const normalized = value.toLowerCase();

  return restrictedClaims.filter(
    (claim) => normalized.includes(claim)
  );
}

Japanese content needs its own reviewed list rather than a literal translation of the English restrictions.

The goal is not to block every emotionally expressive sentence. It is to flag wording that deserves human review.

Warnings might include:

en:result.promise contains “guaranteed”
ja:result.promise contains a restricted certainty claim

A content editor can then decide whether the sentence is appropriate.

Do not use character length as a quality score

It is tempting to require every translation to stay within the same character count as the source.

That does not work across languages.

Share

and:

シェアする

have different character counts but similar interface purposes.

Length checks are still useful as warnings for constrained components:

type LengthRule = {
  key: string;
  maximum: number;
};

const lengthRules: LengthRule[] = [
  {
    key: "fortune.drawButton",
    maximum: 24
  },
  {
    key: "navigation.home",
    maximum: 16
  }
];

Do not fail an entire translation only because it exceeds an arbitrary English-based limit. Instead, send the key to visual review.

Validate HTML and Markdown boundaries

If translations are expected to contain plain text, reject embedded HTML:

function containsHtml(value: string): boolean {
  return /<\/?[a-z][\s\S]*>/i.test(value);
}

if (containsHtml(targetValue)) {
  errors.push(
    `${locale}:${key} contains unexpected HTML`
  );
}

This reduces inconsistent presentation and lowers the risk of unsafe content entering rendering paths.

If rich text is required, define exactly which format and elements are allowed. Do not let individual translation strings invent their own markup conventions.

Produce one readable QA report

A useful validation script should separate errors from warnings.

type ValidationReport = {
  errors: string[];
  warnings: string[];
};

Errors can block deployment:

• Missing required keys

• Invalid placeholder names

• Unsupported value types

• Unexpected HTML

• Invalid locale files

Warnings can request human review:

• Identical source and target values

• Unusually long button labels

• Restricted emotional claims

• Obsolete translation keys

• Punctuation inconsistencies

function printReport(
  report: ValidationReport
): void {
  for (const warning of report.warnings) {
    console.warn(`WARNING: ${warning}`);
  }

  for (const error of report.errors) {
    console.error(`ERROR: ${error}`);
  }

  if (report.errors.length > 0) {
    process.exitCode = 1;
  }
}

The report should tell developers what to fix, not merely say that localization failed.

Run validation in continuous integration

Add the validator to the project scripts:

{
  "scripts": {
    "validate:i18n": "tsx scripts/validate-i18n.ts",
    "test": "npm run validate:i18n && vitest"
  }
}

Then execute it in continuous integration:

- name: Validate translations
  run: npm run validate:i18n

A missing translation is much cheaper to fix before deployment than after a visitor encounters a broken result.

Automated tests are only the first layer

A complete localization QA process also needs visual and human review.

Test each supported language with:

• Narrow mobile screens

• Enlarged text

• Keyboard navigation

• Screen readers where possible

• Slow font loading

• Long dynamic values

• Empty and error states

• Share cards and social previews

A JSON validator cannot determine whether Japanese text feels natural, whether a metaphor survives translation, or whether an interface remains culturally respectful.

Those decisions still require people.

Applying the process to a cultural product

I have been exploring this workflow while working on Ichizenn’s 恋みくじ, a Japanese love-fortune web experience.

The product contains short emotional messages, interface instructions, result categories, and culturally specific terminology. A translation error in this context is not only a cosmetic problem. It can change the emotional meaning of a result.

That makes localization part of the product architecture rather than a final writing task.

Final checklist

Before shipping a new locale, verify that:

• Every required key exists.

• Obsolete keys are reported.

• Placeholders match the source.

• Plain-text fields contain no HTML.

• Restricted claims receive human review.

• Length warnings are visually tested.

• Language attributes are correct.

• Mobile layouts are checked.

• Accessibility behavior remains intact.

• A native speaker reviews the final experience.

Final thoughts

Localization files are executable product content.

They control what visitors read, which actions they understand, and how the application communicates uncertainty, errors, privacy, and trust.

Treating translations as testable data does not remove the need for translators and editors. It gives them a safer system in which to work.

Which localization problems have escaped into production in your projects: missing keys, broken placeholders, layout overflow, or something harder to automate?