Lesson 1.1: File Systems & Extensions Under the Hood

1. Human Impact & Context

When you draft an email or write a document in a word processor, the operating system works behind the scenes to make the visual interface clean and simple. To shield everyday users from technical complexity, operating systems like macOS and Windows deliberately hide file extensions by default.

In general office work, hiding extensions is a minor detail. In localization engineering, it is a leading cause of broken pipelines and failed software builds:

• The Hidden File Mistake: You open a JSON file named strings.json, edit it, and save it using a standard text editor. Unknown to you, the OS quietly appends .txt to the end, turning your file into strings.json.txt.

• The Production Crash: The automated build system or localization management system (LMS) scans the repository strictly looking for strings.json. Because the file extension was altered, the system fails to find the asset, resulting in a failed build or untranslated UI strings in production.

By unmasking hidden file extensions and understanding how directory trees function, you transition from a passive computer user into an intentional digital architect who preserves file integrity across global workflows.

2. Core Concepts & Mechanics

File Extensions: Operating Systems vs. Raw File Data

A file extension (the suffix after the final period in a file name, such as .json, .vtt, or .csv) tells the operating system which program should open the file by default. However, changing a file’s extension does not change the actual structure of the data inside it.

Filename Structure:
[ base_filename ] . [ extension ]
   strings           json

• Hidden Extension Risk: If system extensions are hidden, renaming ui_local.json to ui_local_v2.json in a standard dialog box often produces ui_local_v2.json.txt.

• Explicit Control: Turning extensions ON ensures that every rename, save, or export action preserves the exact file format expected by build tools and translation pipelines.

Navigating Directory Trees & Relative Paths

Software applications rarely store all assets in a single folder. They rely on structured directory trees to organize source code, localized text, and media assets.

project-root/
├── assets/
│   └── loc/
│       ├── en-US/
│       │   └── dialogue.json
│       └── ja-JP/
│           └── dialogue.json
└── src/
    └── index.html

To access localized assets, engineering pipelines use path notation:

1. Absolute Paths: The complete path from the root of the file system (e.g., /Users/username/Projects/app/assets/loc/en-US/dialogue.json or C:\Users\username\Projects\app\assets\loc\en-US\dialogue.json). Absolute paths break when shared with team members because user directory structures differ across machines.

2. Relative Paths: The path relative to the working directory of the project (e.g., assets/loc/ja-JP/dialogue.json or ./assets/loc/ja-JP/dialogue.json). Relative paths ensure that project links remain functional regardless of whose machine or server hosts the repository.

Binary Files vs. Plain Text Files

Localization engineering requires distinguishing between two primary categories of digital files:

3. Real-World Industry Application

                  ┌─────────────────────────────────────────┐
                  │          Localization Assets            │
                  └────────────────────┬────────────────────┘
                                       │
        ┌──────────────────────────────┼──────────────────────────────┐
        ▼                              ▼                              ▼
┌───────────────┐              ┌───────────────┐              ┌───────────────┐
│  Software UI  │              │    Game UI    │              │ Linear Media  │
└───────┬───────┘              └───────┬───────┘              └───────┬───────┘
        │                              │                              │
        ▼                              ▼                              ▼
  i18next JSON                   String Tables                  WebVTT / SRT
 (`en-US.json`)                   (`.csv`)                      (`.vtt`)

• Software UI (Web & Mobile): User interface text is commonly stored in key-value .json or .xml plain text files. A misplaced file extension or corrupt file path prevents the application from loading foreign language text strings.

• Game Localization: Game engines store dialogue arrays and user interface text in .csv or .json plain text files. Pathing errors (e.g., pointing to /assets/loc/ instead of /assets/localization/) result in missing text errors ("MISSING_STRING_KEY") during gameplay.

• Linear Media (Subtitling & Dubbing): Caption tracks are authored in plain text formats like WebVTT (.vtt) or SubRip (.srt). Altering the extension to a binary format renders video players unable to parse timestamps and display subtitle overlays.

4. Cross-Platform Execution (macOS & Windows)

Before opening Visual Studio Code, you must configure your desktop environment to show all file extensions explicitly.

Step 1: Unhide File Extensions in Operating Systems

macOS (Finder)

1. Open Finder.

2. In the top menu bar, click Finder Settings... (or press Cmd + ,).

3. Click the Advanced tab.

4. Check the box for "Show all filename extensions".

Windows (File Explorer)

1. Open File Explorer (press Win + E).

2. Click View in the top ribbon menu.

3. Select Show check File name extensions.

Step 2: Navigating Directory Paths in VS Code

Once system extensions are visible, open Visual Studio Code to inspect relative pathways directly:

1. Open VS Code.

2. Open a project folder:

   • macOS: File Open Folder... (Cmd + O)

   • Windows: File Open Folder... (Ctrl + K, then Ctrl + O)

3. View the Explorer Panel on the left side (Cmd + Shift + E on macOS / Ctrl + Shift + E on Windows).

4. Hover over any file to view its exact relative pathing within the project hierarchy.

5. Next Steps & Lab Practice

Now that you have configured your operating system to show hidden extensions and understood the mechanics of file pathways, you are ready to put these concepts into practice.

Proceed to 🛠️ Hands-On Lab 1.1: Workspace Setup & File Integrity, where you will safely create, move, rename, and verify plain-text files across relative directories in VS Code without corrupting extensions.