# Template Slug Migration Guide

**Last Updated:** 2026-02-18

## Purpose

Migrate template slugs from English to German keyword-based URLs per SEO best practices (Google Search Central: use audience language). Data-driven decisions from SISTRIX and template-candidate-keywords.

## Slug Mapping (Data-Driven)

| Current ID | New Slug | Primary Keyword | Action |
|------------|----------|-----------------|--------|
| shift-planning-advanced | wochenplan-vorlage | wochenplan erstellen vorlage kostenlos | 301 (wochenplan-premium-vorlage was dead keyword) |
| wochenplan-premium-vorlage | wochenplan-vorlage | wochenplan erstellen vorlage kostenlos | 301 (0 vol) |
| time-tracking-basic | stundenzettel-excel-vorlage | stundenzettel vorlage | 301 |
| zeiterfassung-vorlage-excel | stundenzettel-excel-vorlage | stundenzettel vorlage | 301 ("zeiterfassung" not in SISTRIX) |
| payroll-basic | lohnabrechnung-vorlage | lohnabrechnung vorlage | Done (2026-02) |
| employee-onboarding | onboarding-checkliste-vorlage | abwesenheitsnotiz vorlage | Rename + 301 |
| performance-review | mitarbeiterbeurteilung-vorlage | vorlage mitarbeiterbeurteilung | Rename + 301 |
| training-schedule | hygieneschulung-vorlage | hygieneschulung vorlage pdf | Rename + 301 |
| compliance-audit | compliance-checkliste-vorlage | arbeitszeugnis vorlage | Rename + 301 |
| vacation-planning | (merge) | urlaubsantrag vorlage | Merge into urlaubsantrag-vorlage |

**No change:** dienstplan-excel-vorlage, stundenzettel-excel-vorlage, wochenplan-vorlage, and all other German slugs.

## Migration Steps (Per Template)

### 1. Pre-Migration

- [ ] Run `validate-template-slug-keyword-alignment.php --all` (will fail for English slugs)
- [ ] Run `analyze-template-slug-keyword-matrix.php` to confirm recommended slug
- [ ] Grep: `grep -r "template-id" v2/ docs/ --include="*.php" --include="*.json" --include="*.md"` for all references

### 2. Update Registry

- [ ] In `template-registry.json`: change `id` from old to new slug
- [ ] Update `definition_file` path if it references template ID

### 3. Rename Template Data

- [ ] `mv docs/systems/templates/template-data/{old-id} docs/systems/templates/template-data/{new-id}`
- [ ] Update any internal references in template-data JSON files

### 4. Rename Template Definition

- [ ] In `v2/systems/excel-template-generator/data/template-definitions/examples/`: rename `{old-id}.json` to `{new-id}.json`
- [ ] Update registry `definition_file` to match

### 5. Update .htaccess

- [ ] Replace route: `RewriteRule ^vorlagen\/{old-slug}\/?$` with `{new-id}`
- [ ] Add 301 redirect: `RewriteRule ^vorlagen\/{old-slug}\/?$ /vorlagen/{new-slug} [R=301,L,QSA]`
- [ ] Place redirect before the new route

### 6. Update Configs

- [ ] `templates-index-config.php`: update `$publishedTemplatesForIndex`, `$templateSlugToFilterKey`, `$templateIndexCardOverrides`
- [ ] `template-page-config.php`: no change (uses template ID from registry)

### 7. Update Discovery

- [ ] `sitemap-pages.json`: add new URL, remove old
- [ ] `llms.txt`, `llms-full.txt`: update template URLs

### 8. Update Internal Links

- [ ] `templates_carousel.php`: uses slug from config
- [ ] `blog-template-helpers.php`: template URL generation
- [ ] Grep for `/vorlagen/{old-slug}` in all files

### 9. Post-Migration

- [ ] Run `validate-template-slug-keyword-alignment.php --all` (should pass)
- [ ] Run `test-template-redirects.py` (or PHP script)
- [ ] Browser test: old URL redirects to new; new URL returns 200

## Checklist Per Template

```
Template: shift-planning-advanced → wochenplan-premium-vorlage
[ ] template-registry.json
[ ] template-data/{id} dir rename
[ ] template-definitions/examples/{id}.json
[ ] .htaccess (route + redirect)
[ ] templates-index-config.php
[ ] sitemap-pages.json
[ ] llms.txt, llms-full.txt
[ ] Internal links (grep)
[ ] Redirect test
```

## Vacation-Planning Merge

**Do not publish vacation-planning as separate template.** Instead:

1. Add urlaubsplanung section to urlaubsantrag-vorlage content-blocks
2. Set vacation-planning status to `deprecated` in registry
3. Add redirect: `vorlagen/vacation-planning` → `vorlagen/urlaubsantrag-vorlage`
4. Remove from template-data if desired (or keep for reference)

## References

- [SLUG_KEYWORD_ALIGNMENT_AUDIT.md](SLUG_KEYWORD_ALIGNMENT_AUDIT.md)
- [TEMPLATE_PRIORITY_LIST.md](../../v2/systems/excel-template-generator/docs/TEMPLATE_PRIORITY_LIST.md)
- [TEMPLATE_INVENTORY_KEYWORD_WORKFLOW.md](TEMPLATE_INVENTORY_KEYWORD_WORKFLOW.md)
- [docs/development/CANONICAL_URLS_AND_LINKING.md](../../development/CANONICAL_URLS_AND_LINKING.md)