docs: add i18n-state-manager documentation and clean up development section

docs/development/BOOLEAN_PROPERTY_IDENTIFICATION.md

@@ -1,35 +0,0 @@
-## Boolean property identification: contributor notes
-
-This plugin supports using a frontmatter property to identify task notes. When the setting "Identify Properties by" is set to Property, and you configure a Task Property Name/Value pair, the plugin will match notes whose frontmatter property equals the configured value.
-
-### Booleans vs strings in Obsidian frontmatter
-- Obsidian stores checkbox properties as actual boolean values (true/false), not strings.
-- The settings UI stores the Task Property Value as a string (e.g., "true" or "false").
-- To avoid breaking native behavior, the plugin performs boolean-aware comparisons:
-  - String "true" matches frontmatter boolean true
-  - String "false" matches frontmatter boolean false
-  - Case-insensitive for boolean strings
-  - Arrays are supported (e.g., property: [false, true])
-
-### Writing frontmatter on task creation
-- When property-based identification is enabled, TaskService writes the Task Property Name to frontmatter.
-- If Task Property Value equals "true" or "false", the plugin writes a real boolean (true/false) to frontmatter to keep consistency with Obsidian property types.
-
-### Practical guidance for contributors
-- Do not quote boolean values in frontmatter just to satisfy identification; the comparison logic handles booleans.
-- When touching identification logic, preserve:
-  - Strict equality for non-boolean values
-  - Case-insensitive handling for "true"/"false"
-  - Array handling via some(...) semantics
-- Keep the minimal, non-disruptive approach: no heavy parsers or global state stores.
-
-### Tests
-- Unit tests cover boolean identification in MinimalNativeCache and boolean writing in TaskService.
-- See:
-  - tests/unit/utils/MinimalNativeCache.boolean-property.test.ts
-  - tests/unit/services/TaskService.test.ts (coercion tests for true/false)
-
-### Limitations
-- Only boolean coercion is applied. Other types (numbers, links) still use strict equality or existing mapping utilities.
-
-If you extend identification to additional types, add tests and document the comparison rules here to keep behavior predictable and compatible with Obsidian’s native property types.

docs/development/USER_FIELDS_TECHNICAL.md

@@ -1,106 +0,0 @@
-# User Fields - Technical Implementation
-
-This document provides technical details about the User Fields feature implementation for developers contributing to TaskNotes.
-
-## Architecture Overview
-
-User Fields extend TaskNotes' filtering system by allowing users to define custom frontmatter properties that become available as filter options across all views.
-
-### Core Components
-
-**Settings Interface** (`src/settings/TaskNotesSettingTab.ts`)
-- User field configuration UI in Advanced Settings
-- Real-time validation and field management
-- Immediate filter option refresh on changes
-
-**Filter Service** (`src/services/FilterService.ts`)
-- Dynamic filter option generation for user fields
-- Type-aware operator selection based on field type
-- Value normalization for different data types
-
-**Filter Utils** (`src/utils/FilterUtils.ts`)
-- Validation logic for user field operators
-- Evaluation logic for filtering tasks
-- Support for all user field types
-
-**String Splitting** (`src/utils/stringSplit.ts`)
-- Bracket/quote-aware CSV parsing for list fields
-- Preserves wikilinks `[[...]]` and quoted content
-- Single-pass O(n) algorithm for performance
-
-## Data Flow
-
-1. **Configuration**: User defines fields in settings with type information
-2. **Option Generation**: FilterService generates filter options dynamically
-3. **Validation**: FilterUtils validates operator compatibility with field types
-4. **Evaluation**: Filter conditions are evaluated against task frontmatter
-5. **Normalization**: Values are normalized based on field type before comparison
-
-## Field Type Implementation
-
-### Text Fields
-- Direct string comparison
-- Case-insensitive matching for contains/does-not-contain
-- Empty value handling
-
-### Number Fields
-- Numeric extraction from mixed text-number formats
-- Supports values like "2-Medium" → extracts `2`
-- Full comparison operator support (>, <, >=, <=, =, !=)
-
-### Date Fields
-- Natural language date parsing integration
-- ISO date format support
-- Timezone-aware comparisons
-
-### Boolean Fields
-- True/false evaluation
-- Checkbox operator support (is-checked, is-not-checked)
-
-### List Fields
-- Intelligent comma splitting with `splitListPreservingLinksAndQuotes()`
-- Wikilink preservation: `[[Health, Fitness & Mindset]]` treated as single item
-- Quote preservation: `"Focus, Deep Work"` treated as single item
-- Contains/does-not-contain matching against individual list items
-
-## Performance Considerations
-
-**Caching**: Filter options are cached and only regenerated when user fields change
-**Lazy Evaluation**: User field values are only processed when filters are applied
-**Efficient Parsing**: String splitting uses single-pass algorithm
-**Memory Management**: Normalized values are not stored permanently
-
-## Integration Points
-
-**FilterBar Components**: Automatically receive updated filter options
-**View Refreshing**: All view types refresh filter options when user fields change
-**Settings Persistence**: User fields are stored in plugin settings with stable IDs
-**Type Safety**: TypeScript interfaces ensure type consistency across components
-
-## Testing
-
-Unit tests cover:
-- String splitting edge cases with wikilinks and quotes
-- Filter normalization for all field types
-- Operator validation logic
-- Value extraction from mixed formats
-
-Test files:
-- `tests/unit/utils/stringSplit.test.ts`
-- `tests/unit/services/filterService.userListNormalization.test.ts`
-
-## Extension Points
-
-The User Fields system is designed for extensibility:
-
-**New Field Types**: Add new types by extending the type union and implementing normalization logic
-**Custom Operators**: Add operators by updating the FilterOperator type and evaluation logic
-**Advanced Parsing**: Extend string splitting for new content formats
-**UI Enhancements**: Field configuration UI can be extended with additional options
-
-## Migration and Compatibility
-
-**Backward Compatibility**: Existing filters continue to work unchanged
-**Settings Migration**: User fields are optional and don't affect existing configurations
-**Field Mapping Integration**: User fields work alongside existing field mapping system
-**Plugin Compatibility**: Uses standard frontmatter properties, compatible with other plugins

docs/development/i18n-state-manager.md

@@ -0,0 +1,56 @@
+# i18n-state-manager
+
+i18n-state-manager is a translation management tool developed for TaskNotes and published as an open-source npm package. It addresses a limitation common to most translation tools: the inability to detect when translations become outdated after source text changes.
+
+## Purpose
+
+Traditional translation tools can identify missing translations but cannot determine if existing translations correspond to the current source text. When English text changes from "Save task" to "Save task changes", other languages continue displaying translations of the original text. i18n-state-manager solves this by tracking the relationship between source text and translations using cryptographic hashes.
+
+## How It Works
+
+The tool maintains two files:
+
+**Manifest** (`i18n.manifest.json`)
+
+Contains SHA1 hashes of all source language strings. When source text changes, its hash changes.
+
+**State** (`i18n.state.json`)
+
+Records the source hash each translation was created against. By comparing manifest hashes with state hashes, the tool determines whether translations are current, missing, or stale.
+
+A translation is considered:
+
+- **Current**: Source hash in manifest matches the hash recorded in state
+- **Missing**: No translation exists for the key
+- **Stale**: Source hash has changed since the translation was created
+
+## Integration with TaskNotes
+
+TaskNotes uses i18n-state-manager to manage translations across seven languages. The tool runs in continuous integration to prevent deployment of incomplete or outdated translations.
+
+Available commands:
+
+- `i18n-state sync` – Update manifest and state files after changing translations
+- `i18n-state verify` – Check for missing or stale translations (fails on issues)
+- `i18n-state status` – Display translation coverage statistics
+- `i18n-state check-usage` – Verify all translation keys used in code exist in source locale
+- `i18n-state find-unused` – Identify translation keys not referenced in code
+- `i18n-state check-duplicates` – Detect duplicate translation keys
+- `i18n-state generate-template` – Create translation file templates with markers for missing or stale entries
+
+Configuration is stored in `i18n-state.config.json`, which defines the source locale, file locations, and patterns for detecting translation function calls in code.
+
+## Requirements
+
+The tool requires Node.js 16 or later. Commands that scan code (`check-usage`, `find-unused`) require ripgrep to be installed.
+
+## Development History
+
+i18n-state-manager was created during TaskNotes development to address translation drift as the codebase evolved. After proving effective for TaskNotes, it was extracted as a standalone tool to benefit other projects facing similar challenges.
+
+## Installation
+
+```bash
+npm install -D i18n-state-manager
+```
+

mkdocs.yml

@@ -77,6 +77,9 @@ nav:
     - Timezone Handling: TIMEZONE_HANDLING_GUIDE.md
     - UTC Implementation: TIMEZONE_HANDLING_UTC.md
     - Timezone Quick Reference: TIMEZONE_QUICK_REFERENCE.md
+  - Development:
+    - Translation Workflow: development/translations.md
+    - i18n-state-manager: development/i18n-state-manager.md
   - Release Notes: releases.md
   - Troubleshooting: troubleshooting.md
   - Privacy Policy: privacy.md