# How to Handle Missing or Incomplete Translations in the Exercises Dataset

> Fix missing translations in datasets with runtime English fallbacks and JSON Schema validation. Catch translation gaps before deployment for robust data handling.

- Repository: [Hasan Emir Yıldırım/exercises-dataset](https://github.com/hasaneyldrm/exercises-dataset)
- Tags: how-to-guide
- Published: 2026-07-30

---

**To handle missing or incomplete translations in the hasaneyldrm/exercises-dataset, implement a runtime fallback to English (`en`) combined with JSON Schema validation to catch gaps before deployment.**

The **Exercises Dataset** is a multilingual repository containing step-by-step workout instructions across ten languages. While the JSON Schema in [`data/exercises.schema.json`](https://github.com/hasaneyldrm/exercises-dataset/blob/main/data/exercises.schema.json) mandates complete translation coverage, real-world records may omit language keys or contain empty strings, requiring robust handling strategies to maintain application stability.

## Detecting Missing Translations in the Source Files

### Understanding the JSON Schema Requirements

The dataset defines multilingual content through two primary fields: `instructions` (single string) and `instruction_steps` (array of strings). According to [`data/exercises.schema.json`](https://github.com/hasaneyldrm/exercises-dataset/blob/main/data/exercises.schema.json), both fields use a `languageMap` structure that lists ten required language codes: `en`, `es`, `it`, `tr`, `ru`, `zh`, `hi`, `pl`, `ko`, and `fr`. However, schema enforcement only occurs when you explicitly validate the JSON. Without validation, missing keys return as `undefined` in JavaScript or throw `KeyError` exceptions in Python.

### Where Gaps Typically Occur

In [`data/exercises.json`](https://github.com/hasaneyldrm/exercises-dataset/blob/main/data/exercises.json), incomplete translations manifest in three ways:

- **Missing keys**: A language code is entirely absent from the `instructions` or `instruction_steps` object.
- **Empty values**: The key exists but contains an empty string `""` or empty array `[]`.
- **Placeholder text**: Strings like "Translation needed" indicate incomplete localization.

## Strategies for Handling Incomplete Data

### Fallback to English

The most reliable runtime strategy treats the `en` field as a guaranteed baseline. Since English entries are always present in the source data, your application can safely default to `instructions.en` when the requested locale is falsy or empty. This prevents UI crashes and ensures users always see actionable content.

### Validation-First Pipeline

Integrate JSON Schema validation into your CI/CD pipeline using libraries like `jsonschema` (Python) or `ajv` (Node.js). By validating [`data/exercises.json`](https://github.com/hasaneyldrm/exercises-dataset/blob/main/data/exercises.json) against [`data/exercises.schema.json`](https://github.com/hasaneyldrm/exercises-dataset/blob/main/data/exercises.schema.json) during builds, you reject datasets with missing translations before they reach production. This shifts quality control upstream and reduces runtime complexity.

### Placeholder Flags for Translators

When building internal tools or translation dashboards, surface missing entries using visual placeholders like `"⚠️ translation missing"` instead of silent fallbacks. Append a custom boolean field (e.g., `"needs_translation": true`) to records detected with gaps, enabling your team to track localization debt programmatically.

## Code Implementation Examples

### Python: Safe Access with Logging

The following pattern retrieves translations with automatic fallback and operational logging:

```python
import json
import logging
from pathlib import Path

logging.basicConfig(level=logging.INFO)
log = logging.getLogger("exercises")

DATA_PATH = Path("data/exercises.json")
with DATA_PATH.open(encoding="utf-8") as f:
    exercises = json.load(f)

def get_instruction(ex, lang: str) -> str:
    """
    Return instruction for `lang`, falling back to English.
    Logs warnings for missing translations to facilitate cleanup.
    """
    instr = ex["instructions"].get(lang, "").strip()
    if not instr:
        log.warning(
            f"Missing `{lang}` for exercise ID {ex['id']} – falling back to English."
        )
        instr = ex["instructions"]["en"]
    return instr

# Usage

exercise = exercises[0]
print(get_instruction(exercise, "fr"))

```

This approach surfaces data quality issues through logs while maintaining application continuity.

### JavaScript: Runtime Fallback

For Node.js or browser environments, implement a defensive accessor:

```javascript
const exercises = require("./data/exercises.json");

function getInstruction(ex, lang) {
  const translation = ex.instructions[lang];
  if (typeof translation === "string" && translation.trim().length > 0) {
    return translation;
  }
  return `⚠️ ${lang} unavailable – ${ex.instructions.en}`;
}

const ex = exercises[0];
console.log(getInstruction(ex, "ko")); // Falls back if Korean is missing

```

### React Component Integration

Handle missing translations at the UI layer with a functional component:

```tsx
import React from "react";
import exercises from "./data/exercises.json";

type Lang = "en" | "es" | "it" | "tr" | "ru" | "zh" | "hi" | "pl" | "ko" | "fr";

interface Props {
  exerciseId: string;
  lang: Lang;
}

export const Instruction: React.FC<Props> = ({ exerciseId, lang }) => {
  const ex = exercises.find((e) => e.id === exerciseId);
  if (!ex) return <p>Exercise not found</p>;

  const text = ex.instructions[lang] || ex.instructions.en;
  return <p>{text}</p>;
};

```

The component silently falls back to English without throwing runtime errors.

### CI Pipeline Validation

Prevent incomplete data from deploying by validating against the schema:

```python
import json
from jsonschema import validate, ValidationError
from pathlib import Path

schema = json.loads(Path("data/exercises.schema.json").read_text())
exercises = json.loads(Path("data/exercises.json").read_text())

invalid = []
for ex in exercises:
    try:
        validate(instance=[ex], schema=schema)
    except ValidationError as e:
        invalid.append((ex["id"], e.message))

if invalid:
    print("Records missing required translations:")
    for ex_id, msg in invalid:
        print(f"- {ex_id}: {msg}")
    exit(1)

```

Running this script in your CI pipeline ensures that only complete datasets reach production.

## Summary

- **Validate early**: Use [`data/exercises.schema.json`](https://github.com/hasaneyldrm/exercises-dataset/blob/main/data/exercises.schema.json) in CI pipelines to catch missing translations before deployment.
- **Fallback gracefully**: Always implement runtime fallbacks to `instructions.en` or `instruction_steps.en` when target languages are absent.
- **Log for visibility**: Track missing translations with logging or custom flags to guide future dataset improvements.
- **Reference correctly**: Always maintain the [`NOTICE.md`](https://github.com/hasaneyldrm/exercises-dataset/blob/main/NOTICE.md) attribution when using the dataset in production applications.

## Frequently Asked Questions

### What languages are required in the exercises-dataset schema?

The JSON Schema requires ten language codes: `en` (English), `es` (Spanish), `it` (Italian), `tr` (Turkish), `ru` (Russian), `zh` (Chinese), `hi` (Hindi), `pl` (Polish), `ko` (Korean), and `fr` (French). Every exercise record must contain values for all ten codes in both the `instructions` and `instruction_steps` fields, though [`data/exercises.json`](https://github.com/hasaneyldrm/exercises-dataset/blob/main/data/exercises.json) may contain incomplete data that fails strict validation.

### How do I check if a translation is missing before using it?

Check for falsy values or empty strings in the language map. In Python: `if not ex["instructions"].get("fr", "").strip():`. In JavaScript: `if (!ex.instructions.fr || !ex.instructions.fr.trim())`. Always pair this check with a fallback to the `en` field to ensure your application receives a valid string.

### Can I modify the dataset to remove the required language constraint?

You should not modify [`data/exercises.schema.json`](https://github.com/hasaneyldrm/exercises-dataset/blob/main/data/exercises.schema.json) to remove the required field constraints, as this would break compatibility with downstream applications expecting complete multilingual coverage. Instead, handle missing translations in your application logic or preprocess the JSON to fill gaps with English placeholders before consumption.

### Why does the dataset contain empty translation fields despite the schema requirements?

The schema defines the *intended* structure, but [`data/exercises.json`](https://github.com/hasaneyldrm/exercises-dataset/blob/main/data/exercises.json) is not automatically validated on every commit. This allows maintainers to incrementally add translations while keeping the dataset functional. Treat the JSON file as potentially incomplete and implement the defensive programming patterns shown above to handle gaps gracefully.