# dphans/vscode_xcode_localization architecture

> Architecture diagram of the GitHub repository dphans/vscode_xcode_localization, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-26). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/dphans/vscode_xcode_localization
- Repository: https://github.com/dphans/vscode_xcode_localization

## Overview

Xcode Localization is a VS Code extension for editing Xcode String Catalogs and legacy `.strings` files in a spreadsheet-style grid. Users open a localization file, the extension prepares a catalog model and sends it to the webview, where they search, filter, review, and edit translations; edits are applied surgically to preserve clean diffs. A separate Localizations view discovers files and reports progress. The README documents code scanning, git change markers, format warnings, notes, and progress; their details are represented at the subsystem level where source excerpts are incomplete.

Main entry points: [`src/editor/XcstringsEditorProvider.ts`](https://github.com/dphans/vscode_xcode_localization/blob/main/src/editor/XcstringsEditorProvider.ts) (Editor Provider), [`webview/App.tsx`](https://github.com/dphans/vscode_xcode_localization/blob/main/webview/App.tsx) (Grid App), [`src/extension.ts`](https://github.com/dphans/vscode_xcode_localization/blob/main/src/extension.ts) (Extension Activation), [`webview/Grid.tsx`](https://github.com/dphans/vscode_xcode_localization/blob/main/webview/Grid.tsx) (Translation Grid)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_host["VS Code Extension"]
  node_extension["Extension Activation<br/>[extension.ts]"]
  node_editor_provider["Editor Provider"]
  node_protocol["Message Protocol<br/>[protocol.ts]"]
end

subgraph group_model["Catalog and Editing"]
  node_catalog_parser["Catalog Parser<br/>[xcstrings.ts]"]
  node_strings_model["Strings Model<br/>[stringsModel.ts]"]
  node_lproj["Language Grouping<br/>[lproj.ts]"]
  node_surgical_edit["Surgical Editing<br/>[edit.ts]"]
  node_search_filter["Search and Filters<br/>[search.ts]"]
  node_format_validation["Format Validation<br/>[format.ts]"]
  node_git_baseline["Git Baseline<br/>[git.ts]"]
end

subgraph group_ui["Grid Interface"]
  node_webview_app["Grid App<br/>[App.tsx]"]
  node_grid["Translation Grid<br/>[Grid.tsx]"]
  node_language_picker["Language Picker<br/>[LanguagePicker.tsx]"]
  node_diff_display["Change Markers<br/>[diff.ts]"]
end

subgraph group_discovery["Workspace Discovery"]
  node_tree_provider["Localizations View"]
end

node_user(("Translator"))
node_vscode["VS Code"]
node_localization_files["Localization Files"]
node_git_head["Git HEAD"]
node_source_code["Swift / Obj-C Code"]

node_user -->|"opens file"| node_vscode
node_vscode -->|"activates"| node_extension
node_extension -->|"registers editor"| node_editor_provider
node_extension -->|"registers view"| node_tree_provider
node_vscode -->|"opens document"| node_editor_provider
node_editor_provider -->|"reads and watches"| node_localization_files
node_editor_provider -->|"resolves siblings"| node_lproj
node_editor_provider -->|"builds legacy model"| node_strings_model
node_editor_provider -->|"parses catalog"| node_catalog_parser
node_editor_provider -->|"loads baseline"| node_git_baseline
node_git_baseline -->|"reads committed text"| node_git_head
node_editor_provider -->|"sends model and updates"| node_webview_app
node_webview_app -->|"sends edit requests"| node_editor_provider
node_webview_app -->|"uses message types"| node_protocol
node_editor_provider -->|"uses message types"| node_protocol
node_webview_app -->|"parses catalog text"| node_catalog_parser
node_webview_app -->|"searches entries"| node_search_filter
node_webview_app -->|"checks specifiers"| node_format_validation
node_webview_app -->|"renders entries"| node_grid
node_grid -->|"offers language selection"| node_language_picker
node_grid -->|"shows baseline changes"| node_diff_display
node_editor_provider -->|"computes text edits"| node_surgical_edit
node_editor_provider -->|"writes document edits"| node_localization_files
node_tree_provider -->|"scans workspace files"| node_localization_files
node_tree_provider -->|"opens selected file"| node_editor_provider
node_user -->|"edits and filters"| node_webview_app
node_webview_app -.->|"requests code scan"| node_source_code
node_webview_app -.->|"requests code search"| node_vscode

click node_extension "https://github.com/dphans/vscode_xcode_localization/blob/main/src/extension.ts"
click node_editor_provider "https://github.com/dphans/vscode_xcode_localization/blob/main/src/editor/XcstringsEditorProvider.ts"
click node_protocol "https://github.com/dphans/vscode_xcode_localization/blob/main/src/shared/protocol.ts"
click node_catalog_parser "https://github.com/dphans/vscode_xcode_localization/blob/main/src/shared/xcstrings.ts"
click node_strings_model "https://github.com/dphans/vscode_xcode_localization/blob/main/src/editor/stringsModel.ts"
click node_lproj "https://github.com/dphans/vscode_xcode_localization/blob/main/src/editor/lproj.ts"
click node_surgical_edit "https://github.com/dphans/vscode_xcode_localization/blob/main/src/shared/edit.ts"
click node_search_filter "https://github.com/dphans/vscode_xcode_localization/blob/main/src/shared/search.ts"
click node_format_validation "https://github.com/dphans/vscode_xcode_localization/blob/main/src/shared/format.ts"
click node_git_baseline "https://github.com/dphans/vscode_xcode_localization/blob/main/src/editor/git.ts"
click node_tree_provider "https://github.com/dphans/vscode_xcode_localization/blob/main/src/tree/LocalizationsTreeProvider.ts"
click node_webview_app "https://github.com/dphans/vscode_xcode_localization/blob/main/webview/App.tsx"
click node_grid "https://github.com/dphans/vscode_xcode_localization/blob/main/webview/Grid.tsx"
click node_language_picker "https://github.com/dphans/vscode_xcode_localization/blob/main/webview/LanguagePicker.tsx"
click node_diff_display "https://github.com/dphans/vscode_xcode_localization/blob/main/webview/diff.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_extension,node_editor_provider,node_protocol toneBlue
class node_catalog_parser,node_strings_model,node_lproj,node_surgical_edit,node_search_filter,node_format_validation,node_git_baseline toneAmber
class node_webview_app,node_grid,node_language_picker,node_diff_display toneMint
class node_tree_provider toneRose
class node_user,node_vscode,node_localization_files,node_git_head,node_source_code toneIndigo
```

## Components

### VS Code Extension

- [Extension Activation](https://github.com/dphans/vscode_xcode_localization/blob/main/src/extension.ts): `src/extension.ts`
- [Editor Provider](https://github.com/dphans/vscode_xcode_localization/blob/main/src/editor/XcstringsEditorProvider.ts): `src/editor/XcstringsEditorProvider.ts`
- [Message Protocol](https://github.com/dphans/vscode_xcode_localization/blob/main/src/shared/protocol.ts): `src/shared/protocol.ts`

### Catalog and Editing

- [Catalog Parser](https://github.com/dphans/vscode_xcode_localization/blob/main/src/shared/xcstrings.ts): `src/shared/xcstrings.ts`
- [Strings Model](https://github.com/dphans/vscode_xcode_localization/blob/main/src/editor/stringsModel.ts): `src/editor/stringsModel.ts`
- [Language Grouping](https://github.com/dphans/vscode_xcode_localization/blob/main/src/editor/lproj.ts): `src/editor/lproj.ts`
- [Surgical Editing](https://github.com/dphans/vscode_xcode_localization/blob/main/src/shared/edit.ts): `src/shared/edit.ts`
- [Search and Filters](https://github.com/dphans/vscode_xcode_localization/blob/main/src/shared/search.ts): `src/shared/search.ts`
- [Format Validation](https://github.com/dphans/vscode_xcode_localization/blob/main/src/shared/format.ts): `src/shared/format.ts`
- [Git Baseline](https://github.com/dphans/vscode_xcode_localization/blob/main/src/editor/git.ts): `src/editor/git.ts`

### Grid Interface

- [Grid App](https://github.com/dphans/vscode_xcode_localization/blob/main/webview/App.tsx): `webview/App.tsx`
- [Translation Grid](https://github.com/dphans/vscode_xcode_localization/blob/main/webview/Grid.tsx): `webview/Grid.tsx`
- [Language Picker](https://github.com/dphans/vscode_xcode_localization/blob/main/webview/LanguagePicker.tsx): `webview/LanguagePicker.tsx`
- [Change Markers](https://github.com/dphans/vscode_xcode_localization/blob/main/webview/diff.ts): `webview/diff.ts`

### Workspace Discovery

- [Localizations View](https://github.com/dphans/vscode_xcode_localization/blob/main/src/tree/LocalizationsTreeProvider.ts): `src/tree/LocalizationsTreeProvider.ts`

### Other components

- **Translator**
- **VS Code**
- **Localization Files**
- **Git HEAD**
- **Swift / Obj-C Code**

## Connections

- Translator → VS Code: opens file
- VS Code → Extension Activation: activates
- Extension Activation → Editor Provider: registers editor
- Extension Activation → Localizations View: registers view
- VS Code → Editor Provider: opens document
- Editor Provider → Localization Files: reads and watches
- Editor Provider → Language Grouping: resolves siblings
- Editor Provider → Strings Model: builds legacy model
- Editor Provider → Catalog Parser: parses catalog
- Editor Provider → Git Baseline: loads baseline
- Git Baseline → Git HEAD: reads committed text
- Editor Provider → Grid App: sends model and updates
- Grid App → Editor Provider: sends edit requests
- Grid App → Message Protocol: uses message types
- Editor Provider → Message Protocol: uses message types
- Grid App → Catalog Parser: parses catalog text
- Grid App → Search and Filters: searches entries
- Grid App → Format Validation: checks specifiers
- Grid App → Translation Grid: renders entries
- Translation Grid → Language Picker: offers language selection
- Translation Grid → Change Markers: shows baseline changes
- Editor Provider → Surgical Editing: computes text edits
- Editor Provider → Localization Files: writes document edits
- Localizations View → Localization Files: scans workspace files
- Localizations View → Editor Provider: opens selected file
- Translator → Grid App: edits and filters
- Grid App → Swift / Obj-C Code: requests code scan
- Grid App → VS Code: requests code search