Add project documentation and translation guide (#174)

Author: dohsimpson

.dockerignore

@@ -7,3 +7,5 @@ Dockerfile
 node_modules
 npm-debug.log
 data
+CLAUDE.md
+docs/

CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## Version 0.2.25
+
+### Added
+
+* 🌍 Added Catalan language support (Català)
+
+### Fixed
+
+* Translation files consistency: Added missing UserForm keys to English and Korean translations
+
 ## Version 0.2.24
 
 ### Added

CLAUDE.md

@@ -0,0 +1,91 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+HabitTrove is a gamified habit tracking PWA built with Next.js 15, TypeScript, and Jotai state management. Users earn coins for completing habits and can redeem them for rewards. Features multi-user support with admin capabilities and shared ownership of habits/wishlist items.
+
+## Essential Commands
+
+### Development
+- `npm run dev` - Start development server with Turbopack
+- `npm run setup:dev` - Full setup: installs bun, dependencies, runs typecheck and lint
+- `npm install --force` - Install dependencies (force flag required)
+
+### Quality Assurance (Run these before committing)
+- `npm run typecheck` - TypeScript type checking (required)
+- `npm run lint` - ESLint code linting (required)
+- `npm test` - Run tests with Bun
+- `npm run build` - Build production version
+
+### Docker Deployment
+- `npm run docker-build` - Build Docker image locally
+- `docker compose up -d` - Run with docker-compose (recommended)
+- Requires `AUTH_SECRET` environment variable: `openssl rand -base64 32`
+
+## Architecture Overview
+
+### State Management (Jotai)
+- **Central atoms**: `habitsAtom`, `coinsAtom`, `wishlistAtom`, `usersAtom` in `lib/atoms.ts`
+- **Derived atoms**: Computed values like `dailyHabitsAtom`, `coinsBalanceAtom`
+- **Business logic hooks**: `useHabits`, `useCoins`, `useWishlist` in `/hooks`
+
+### Data Models & Ownership
+- **Individual ownership**: `CoinTransaction` has single `userId`
+- **Shared ownership**: `Habit` and `WishlistItemType` have `userIds: string[]` array
+- **Admin features**: Admin users can view/manage any user's data via dropdown selectors
+- **Data persistence**: JSON files in `/data` directory with automatic `/backups`
+
+### Key Components Structure
+- **Feature components**: `HabitList`, `CoinsManager`, `WishlistManager` - main page components
+- **Modal components**: `AddEditHabitModal`, `AddEditWishlistItemModal`, `UserSelectModal`
+- **UI components**: `/components/ui` - shadcn/ui based components
+
+### Authentication & Users
+- NextAuth.js v5 with multi-user support
+- User permissions: regular users vs admin users
+- Admin dropdown patterns: Similar implementation across Habits/Wishlist pages (reference CoinsManager for pattern)
+
+### Internationalization
+- `next-intl` with messages in `/messages/*.json`
+- Supported languages: English, Spanish, German, French, Russian, Chinese, Japanese
+
+## Code Patterns
+
+### Component Structure
+```typescript
+// Standard component pattern:
+export default function ComponentName() {
+  const [data, setData] = useAtom(dataAtom)
+  const { businessLogicFunction } = useCustomHook()
+  // Component logic
+}
+```
+
+### Hook Patterns
+- Custom hooks accept options: `useHabits({ selectedUser?: string })`
+- Return destructured functions and computed values
+- Handle both individual and shared ownership models
+
+### Shared Ownership Pattern
+```typescript
+// Filtering for shared ownership:
+const userItems = allItems.filter(item => 
+  item.userIds && item.userIds.includes(targetUserId)
+)
+```
+
+### Admin Dropdown Pattern
+Reference `CoinsManager.tsx:107-119` for admin user selection implementation. Similar pattern should be applied to Habits and Wishlist pages.
+
+## Data Safety
+- Always backup `/data` before major changes
+- Test with existing data files to prevent data loss
+- Validate user permissions for all data operations
+- Handle migration scripts carefully (see PLAN.md for shared ownership migration)
+
+## Performance Considerations
+- State updates use immutable patterns
+- Large dataset filtering happens at hook level
+- Derived atoms prevent unnecessary re-renders

README.md

@@ -20,7 +20,7 @@ Want to try HabitTrove before installing? Visit the public [demo instance](https
 - 💰 Create a wishlist of rewards to redeem with earned coins
 - 📊 View your habit completion streaks and statistics
 - 📅 Calendar heatmap to visualize your progress (WIP)
-- 🌍 Multi-language support (English, Español, Deutsch, Français, Русский, 简体中文, 한국어, 日本語)
+- 🌍 Multi-language support (English, Español, Català, Deutsch, Français, Русский, 简体中文, 한국어, 日本語)
 - 🌙 Dark mode support
 - 📲 Progressive Web App (PWA) support
 - 💾 Automatic daily backups with rotation

app/settings/page.tsx

@@ -229,6 +229,7 @@ export default function SettingsPage() {
                 {/* Add more languages as needed */}
                 <option value="en">English</option>
                 <option value="es">Español</option>
+                <option value="ca">Català</option>
                 <option value="de">Deutsch</option>
                 <option value="fr">Français</option>
                 <option value="ru">Русский</option>

docs/translation-guide.md

@@ -0,0 +1,77 @@
+# Language Guide
+
+## Adding/Updating Translations
+
+### Adding a New Language
+
+To add a new language translation to HabitTrove:
+
+1. **Create translation file**: 
+   - Copy `messages/en.json` as a template
+   - Save as `messages/{language-code}.json` (e.g., `ko.json` for Korean)
+   - Translate all values while preserving keys and placeholder variables like `{username}`, `{count}`, etc.
+
+2. **Validate translation structure**:
+   ```bash
+   # Ensure JSON is valid
+   jq empty messages/{language-code}.json
+   
+   # Compare structure with English (should show no differences)
+   diff <(jq -S . messages/en.json | jq -r 'keys | sort | .[]') <(jq -S . messages/{language-code}.json | jq -r 'keys | sort | .[]')
+   ```
+
+3. **Add language option to UI**:
+   - Edit `app/settings/page.tsx`
+   - Add new `<option value="{language-code}">{Language Name}</option>` in alphabetical order
+
+4. **Update documentation**:
+   - Add language to README.md supported languages list
+   - Create new changelog entry with version bump
+   - Update package.json version
+
+### Example: Adding Korean (한국어)
+
+```bash
+# 1. Copy translation file
+cp /path/to/ko.json messages/ko.json
+
+# 2. Add to settings page
+# Add: <option value="ko">한국어</option>
+
+# 3. Update README.md
+# Change: 简体中文, 日본語
+# To: 简체中文, 한국어, 日본語
+
+# 4. Add changelog entry
+# Create new version section with language addition
+
+# 5. Bump package version
+# Update version in package.json
+```
+
+### Translation Quality Guidelines
+
+- Use natural, contextually appropriate expressions
+- Maintain consistent terminology throughout
+- Preserve all placeholder variables exactly: `{username}`, `{count}`, `{target}`, etc.
+- Use appropriate formality level for the target language
+- Ensure JSON structure matches English file exactly (385 total keys)
+
+### Validation Commands
+
+```bash
+# Check JSON validity
+jq empty messages/{lang}.json
+
+# Compare key structure
+node -e "
+const en = require('./messages/en.json');
+const target = require('./messages/{lang}.json');
+// ... deep key comparison script
+"
+
+# Verify placeholder consistency
+grep -o '{[^}]*}' messages/en.json | sort | uniq > en_vars.txt
+grep -o '{[^}]*}' messages/{lang}.json | sort | uniq > {lang}_vars.txt
+diff en_vars.txt {lang}_vars.txt
+```