Refactor locale system: align types with usage, add CMS formatting docs (#59)
* Initial plan * Initial analysis: understanding locale system issues Co-authored-by: denshooter <44590296+denshooter@users.noreply.github.com> * Fix translation types to match actual component usage Co-authored-by: denshooter <44590296+denshooter@users.noreply.github.com> * Add comprehensive locale system documentation and fix API route types Co-authored-by: denshooter <44590296+denshooter@users.noreply.github.com> * Address code review feedback: improve readability and translate comments to English Co-authored-by: denshooter <44590296+denshooter@users.noreply.github.com> --------- Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> Co-authored-by: denshooter <44590296+denshooter@users.noreply.github.com>
This commit is contained in:
Copilot
136
docs/LOCALE_IMPROVEMENTS_SUMMARY.md
Normal file
136
docs/LOCALE_IMPROVEMENTS_SUMMARY.md
Normal file
@@ -0,0 +1,136 @@
|
||||
# Locale System Improvements - Summary
|
||||
|
||||
## Problem Statement (Original)
|
||||
|
||||
> The locale stuff is not really working please fix this and bring more structure to it i think there are to many field it dont know how exists. Then i have the question on how i can design stuff then when i use directus as a cms. because some words i maybe want to be writting thicker or so.
|
||||
|
||||
## Issues Identified
|
||||
|
||||
1. **Confusing translation system** - Mix of Directus API + JSON fallbacks with unclear flow
|
||||
2. **Too many fields** - Translation loaders had many keys that don't actually exist or aren't used
|
||||
3. **Type mismatches** - TypeScript interfaces didn't match actual component usage
|
||||
4. **Missing documentation** - No clear guide on how the locale system works
|
||||
5. **No rich text support guidance** - No documentation on how to style text (bold, italic, etc.) in Directus
|
||||
|
||||
## Changes Made
|
||||
|
||||
### 1. Fixed Translation Types (`types/translations.ts`)
|
||||
|
||||
**Before**: Types had many unused fields and wrong structure
|
||||
- `AboutTranslations` had fake `interests` structure that was never used
|
||||
- `HeroTranslations` had fields like `greeting`, `name`, `role` that don't exist
|
||||
- `FooterTranslations` had nested `links` structure and wrong keys
|
||||
- `ContactTranslations` was missing many form validation error keys
|
||||
|
||||
**After**: All types now match actual component usage
|
||||
- Removed all unused/fake fields
|
||||
- Added all missing fields that components actually use
|
||||
- Flattened overly-nested structures
|
||||
- Types now provide accurate autocomplete and type checking
|
||||
|
||||
### 2. Fixed Translation Loaders (`lib/translations-loader.ts`)
|
||||
|
||||
**Before**:
|
||||
- Loaders tried to fetch non-existent keys
|
||||
- Had confusing comments like "Diese Keys sind NICHT korrekt"
|
||||
- Mapped keys to wrong structure (e.g., hobbies mapped to interests)
|
||||
|
||||
**After**:
|
||||
- All loaders now fetch only keys that exist in JSON files
|
||||
- Removed misleading comments
|
||||
- Correct mapping from keys to return structure
|
||||
- Clear, straightforward code
|
||||
|
||||
### 3. Fixed API Routes
|
||||
|
||||
- Updated `app/api/i18n/[namespace]/route.ts` for Next.js 15 async params
|
||||
- Fixed `app/api/projects/[id]/translation/route.ts` Prisma null handling
|
||||
|
||||
### 4. Added Comprehensive Documentation
|
||||
|
||||
Created **`docs/LOCALE_SYSTEM.md`** with:
|
||||
- Complete architecture explanation
|
||||
- All translation structures with TypeScript types
|
||||
- How to use translations in server/client components
|
||||
- **Rich text content guide** - How to format text in Directus CMS
|
||||
- Adding new translations workflow
|
||||
- Fallback behavior explanation
|
||||
- Best practices
|
||||
- Troubleshooting guide
|
||||
|
||||
### 5. Clarified Directus Integration
|
||||
|
||||
Updated **`DIRECTUS_MIGRATION.md`**:
|
||||
- Made it clear that Directus is **optional**
|
||||
- Emphasized JSON files work perfectly without CMS
|
||||
- Removed confusing sections
|
||||
- Added "what was fixed" section
|
||||
- Better troubleshooting
|
||||
|
||||
### 6. Updated Main README
|
||||
|
||||
Added link to locale system documentation for easy discovery.
|
||||
|
||||
## How to Use (For Developers)
|
||||
|
||||
### Static Translations (Most Common)
|
||||
|
||||
All translations are in `messages/en.json` and `messages/de.json`. Components use:
|
||||
|
||||
```tsx
|
||||
const t = useTranslations('home.hero');
|
||||
return <h1>{t('title')}</h1>;
|
||||
```
|
||||
|
||||
### Rich Text Content (For Styling)
|
||||
|
||||
For content that needs **bold**, *italic*, lists, etc.:
|
||||
|
||||
1. In component:
|
||||
```tsx
|
||||
const [cmsDoc, setCmsDoc] = useState<JSONContent | null>(null);
|
||||
|
||||
useEffect(() => {
|
||||
fetch(`/api/content/page?key=home-hero&locale=${locale}`)
|
||||
.then(res => res.json())
|
||||
.then(data => setCmsDoc(data?.content?.content));
|
||||
}, [locale]);
|
||||
|
||||
return cmsDoc ? <RichTextClient doc={cmsDoc} /> : <p>{t('fallback')}</p>;
|
||||
```
|
||||
|
||||
2. In Directus CMS, use the rich text editor to format text
|
||||
|
||||
### Adding New Translations
|
||||
|
||||
1. Add to both `messages/en.json` and `messages/de.json`
|
||||
2. Update types in `types/translations.ts` if needed
|
||||
3. Add loader in `lib/translations-loader.ts` if needed
|
||||
4. Use in components with `useTranslations()`
|
||||
|
||||
## Testing
|
||||
|
||||
- ✅ Application builds successfully
|
||||
- ✅ All unit tests pass (11 test suites, 17 tests)
|
||||
- ✅ TypeScript types are correct
|
||||
- ✅ No more confusing "NICHT korrekt" comments
|
||||
- ✅ All translation keys align with JSON files
|
||||
|
||||
## Benefits
|
||||
|
||||
1. **Clear structure** - Developers now know exactly which translations exist
|
||||
2. **Type safety** - TypeScript autocomplete works correctly
|
||||
3. **Documentation** - Complete guide on how everything works
|
||||
4. **Rich text support** - Clear instructions on how to style text in CMS
|
||||
5. **Maintainability** - No more guessing which fields are real vs fake
|
||||
6. **Flexibility** - Works perfectly without Directus, can add it later if needed
|
||||
|
||||
## Migration Guide for Existing Code
|
||||
|
||||
No breaking changes! All existing code continues to work because:
|
||||
- We only removed unused types/keys
|
||||
- We fixed types to match what was already being used
|
||||
- All JSON files remain unchanged
|
||||
- All component usage remains the same
|
||||
|
||||
The changes are purely organizational and documentation improvements.
|
||||
Reference in New Issue
Block a user