How to Use the instruction_steps Array for UI Display in the Exercises Dataset

Yes, the instruction_steps array is specifically designed as an ordered list of step-by-step instructions for direct UI rendering across multiple languages.

The hasaneyldrm/exercises-dataset repository provides a structured fitness dataset where each exercise includes an instruction_steps object that stores localized instruction arrays. This format eliminates the need to parse long text paragraphs, allowing you to render numbered lists, carousels, or collapsible panels directly from the JSON data.

Understanding the instruction_steps Data Structure

The dataset stores multilingual instructions in two complementary formats within each exercise object in data/exercises.json. The instruction_steps field contains an object with language keys mapping to ordered string arrays.

The supported language keys include: en, es, it, tr, ru, zh, hi, pl, ko, and fr. Each key contains an array where index 0 represents step one, index 1 represents step two, and so on, guaranteeing deterministic ordering for UI consumption.

As defined in the data/exercises.schema.json file and documented in the README, this structure exists alongside the legacy instructions string field, which provides the same content as a single paragraph for backward compatibility.

Why Use instruction_steps for UI Rendering

Consistent ordering – The array indices explicitly define the sequence of movements, eliminating ambiguity about which action comes first when rendering step-by-step guides.

Internationalization-ready – Every language follows the identical array structure, allowing you to switch locales by changing the object key (e.g., instruction_steps.es to instruction_steps.fr) without modifying your UI rendering logic.

Framework compatibility – Modern frontend frameworks including React, Vue, and Angular natively support mapping over string arrays to generate list elements, reducing transformation overhead.

Implementation Examples by Platform

React Component Implementation

The following TypeScript component demonstrates type-safe access to the instruction_steps array:

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

type Props = {
  exerciseId: string;
  language: keyof typeof exercises[0]["instruction_steps"];
};

export const InstructionSteps: React.FC<Props> = ({ exerciseId, language }) => {
  const exercise = exercises.find((e) => e.id === exerciseId);
  if (!exercise) return null;

  const steps = exercise.instruction_steps[language];

  return (
    <ol>
      {steps.map((step, idx) => (
        <li key={idx}>{step}</li>
      ))}
    </ol>
  );
};

Vanilla JavaScript (Browser/Node)

For environments without framework overhead, iterate directly over the array:

import exercises from "./data/exercises.json";

// Access English steps for the first exercise
const enSteps = exercises[0].instruction_steps.en;

// Render as an ordered list
const ul = document.createElement("ul");
enSteps.forEach(step => {
  const li = document.createElement("li");
  li.textContent = step;
  ul.appendChild(li);
});
document.body.appendChild(ul);

Python with Pandas

When analyzing the dataset in data science workflows, use pd.json_normalize to flatten the nested structure:

import json
import pandas as pd

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

df = pd.json_normalize(data, sep="_")

# Retrieve English steps for exercise "0001"

steps = df.loc[df.id == "0001", "instruction_steps_en"].iloc[0]
for i, step in enumerate(steps, 1):
    print(f"{i}. {step}")

Swift (iOS)

For native iOS applications, decode the nested dictionary structure directly:

struct Exercise: Decodable {
    let id: String
    let instruction_steps: [String: [String]]
}

// Load from bundle
let url = Bundle.main.url(forResource: "exercises", withExtension: "json")!
let data = try Data(contentsOf: url)
let exercises = try JSONDecoder().decode([Exercise].self, from: data)

// Display English steps
let steps = exercises.first!.instruction_steps["en"]!
// Use steps array to populate UITableView or SwiftUI List

Key Source Files and References

• data/exercises.json – Contains 1,324 exercise objects with the instruction_steps field for all supported languages.
• data/exercises.schema.json – JSON Schema formally defining the instruction_steps structure and language key constraints.
• index.html – Reference implementation showing how the dataset renders instructions in a browser interface.
• setup.html – Developer documentation for importing and accessing the dataset from various programming languages.
• README.md – Complete data model documentation including the instruction_steps specification at line 93.

Summary

• The instruction_steps array provides ordered, language-specific instruction sequences ideal for UI step lists.
• Ten languages are supported under consistent object keys within each exercise record.
• The format integrates directly with React, Vue, Angular, Swift, and Python without requiring text parsing or string splitting.
• Source files data/exercises.json and data/exercises.schema.json provide the authoritative structure and validation rules.

Frequently Asked Questions

What is the difference between instructions and instruction_steps?

The instructions.<lang> property contains a single string paragraph describing the exercise, while instruction_steps.<lang> provides the same content split into an ordered array of individual steps. Use the string format for simple text displays and the array format when you need to render numbered lists or step-by-step walkthroughs.

Which languages are supported in the instruction_steps array?

The dataset includes instruction_steps for English (en), Spanish (es), Italian (it), Turkish (tr), Russian (ru), Chinese (zh), Hindi (hi), Polish (pl), Korean (ko), and French (fr). Each exercise contains all ten language keys when translations are available.

How do I handle missing translations in instruction_steps?

According to the schema in data/exercises.schema.json, the instruction_steps object requires all supported language keys to be present. If a specific translation is missing, the array typically contains the English fallback or an empty array, depending on the dataset version. Always verify array length before rendering or implement a fallback to instruction_steps.en.

Is the instruction_steps array suitable for accessibility features?

Yes, the ordered array structure is ideal for accessibility implementations. You can map each array element to <li> elements within an <ol> tag in HTML, which screen readers announce with proper step numbering. The deterministic ordering also supports voice navigation commands like "next step" or "previous step" in assistive technologies.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}