Upload TRANSLATION.md with huggingface_hub

TRANSLATION.md

@@ -0,0 +1,606 @@
+# 🌍 Translation Guide for BentoPDF
+
+This guide will help you add new languages or improve existing translations for BentoPDF.
+
+## Table of Contents
+
+- [Overview](#overview)
+- [Quick Start](#quick-start)
+- [Adding a New Language](#adding-a-new-language)
+- [Translation File Structure](#translation-file-structure)
+- [Where Translations Are Used](#where-translations-are-used)
+- [Testing Your Translations](#testing-your-translations)
+- [Translation Guidelines](#translation-guidelines)
+- [Common Issues](#common-issues)
+
+---
+
+## Overview
+
+BentoPDF uses **i18next** for internationalization (i18n). Currently supported languages:
+
+- **English** (`en`) - Default
+- **Belarusian** (`be`)
+- **German** (`de`)
+- **Spanish** (`es`)
+- **French** (`fr`)
+- **Italian** (`it`)
+- **Portuguese** (`pt`)
+- **Turkish** (`tr`)
+- **Vietnamese** (`vi`)
+- **Indonesian** (`id`)
+- **Chinese** (`zh`)
+- **Traditional Chinese (Taiwan)** (`zh-TW`)
+
+The app automatically detects the language from the URL path:
+
+- `/` or `/en/` → English (default)
+- `/de/` → German
+- `/fr/` → French
+- etc.
+
+### Architecture
+
+BentoPDF uses a **static pre-rendering** approach for SEO-optimized i18n:
+
+1. **Build time**: `scripts/generate-i18n-pages.mjs` generates localized HTML files in `dist/{lang}/`
+2. **Dev/Preview**: `languageRouterPlugin` in `vite.config.ts` handles URL rewriting
+3. **Production**: Nginx serves static files directly from language directories
+
+---
+
+## Quick Start
+
+**To improve existing translations:**
+
+1. Navigate to `public/locales/{language}/common.json` and `public/locales/{language}/tools.json`
+2. Find the key you want to update
+3. Change the translation value
+4. Save and test
+
+**To add a new language (e.g., Japanese `ja`):**
+
+1. Copy `public/locales/en/` to `public/locales/ja/`
+2. Translate all values in both `ja/common.json` and `ja/tools.json`
+3. Add Japanese to `supportedLanguages` and `languageNames` in `src/js/i18n/i18n.ts`
+4. Add `'ja'` to `SUPPORTED_LANGUAGES` in `vite.config.ts`
+5. Restart the dev server
+6. Run `npm run build` to generate static language pages
+7. Test thoroughly
+
+---
+
+## Adding a New Language
+
+Let's add **Spanish** as an example:
+
+### Step 1: Create Translation Files
+
+```bash
+# Create the directory
+mkdir -p public/locales/es
+
+# Copy the English template
+cp public/locales/en/common.json public/locales/es/common.json
+```
+
+### Step 2: Translate the JSON Files
+
+Open `public/locales/es/common.json` and translate all the values:
+
+```json
+{
+  "nav": {
+    "home": "Inicio",
+    "about": "Acerca de",
+    "contact": "Contacto",
+    "allTools": "Todas las herramientas"
+  },
+  "hero": {
+    "title": "Tu conjunto de herramientas PDF gratuito y seguro",
+    "subtitle": "Combina, divide, comprime y edita archivos PDF directamente en tu navegador."
+  }
+  // ... continue translating all keys
+}
+```
+
+⚠️ **Important**: Only translate the **values**, NOT the keys!
+
+✅ **Correct:**
+
+```json
+"home": "Inicio"
+```
+
+❌ **Wrong:**
+
+```json
+"inicio": "Inicio"
+```
+
+Then do the same for `public/locales/fr/tools.json` to translate all tool names and descriptions.
+
+### Step 3: Register the Language
+
+Edit `src/js/i18n/i18n.ts`:
+
+```typescript
+// Add 'fr' to supported languages
+export const supportedLanguages = ['en', 'de', 'es', 'fr', 'zh', 'vi'] as const;
+export type SupportedLanguage = (typeof supportedLanguages)[number];
+
+// Add French display name
+export const languageNames: Record<SupportedLanguage, string> = {
+  en: 'English',
+  de: 'Deutsch',
+  fr: 'Français', // ← Add this
+};
+```
+
+### Step 4: Update Vite Configuration
+
+In `vite.config.ts`, add your language to the `SUPPORTED_LANGUAGES` array:
+
+```typescript
+const SUPPORTED_LANGUAGES = [
+  'en',
+  'de',
+  'es',
+  'zh',
+  'zh-TW',
+  'vi',
+  'it',
+  'id',
+  'tr',
+  'fr',
+  'pt',
+  'ja',
+] as const;
+```
+
+> **Important**: This is required for both dev server routing and the build-time i18n generation.
+
+### Step 5: Test Your Translation
+
+```bash
+# Restart the dev server
+npm run dev
+
+# Visit the Japanese version
+# http://localhost:5173/ja/
+```
+
+### Step 6: Build and Verify Static Files
+
+```bash
+# Run build (includes i18n page generation)
+npm run build
+
+# Verify files were created
+ls dist/ja/
+# Should show: index.html, merge-pdf.html, etc.
+```
+
+---
+
+## Translation File Structure
+
+The `common.json` file is organized into logical sections:
+
+```json
+{
+  "nav": {
+    // Navigation menu items
+  },
+  "hero": {
+    // Homepage hero section
+  },
+  "features": {
+    // Features section
+  },
+  "tools": {
+    // Tool names and descriptions
+  },
+  "upload": {
+    // File upload UI
+  },
+  "settings": {
+    // Settings modal and keyboard shortcuts
+  },
+  "faq": {
+    // FAQ section
+  },
+  "footer": {
+    // Footer links and text
+  },
+  "compliance": {
+    // Security compliance information
+  },
+  "testimonials": {
+    // User testimonials
+  },
+  "support": {
+    // Support section
+  },
+  "alert": {
+    // Alert and error messages
+  }
+}
+```
+
+### Key Naming Convention
+
+- Use **camelCase** for keys: `"deletePage"` not `"delete_page"`
+- Use **nested objects** for organization: `"nav.home"` is represented as:
+  ```json
+  {
+    "nav": {
+      "home": "Home"
+    }
+  }
+  ```
+- Be descriptive: `"shortcutsWarning"` is better than `"warning1"`
+
+---
+
+## Where Translations Are Used
+
+### 1. HTML Templates (`data-i18n` attribute)
+
+```html
+<!-- Translation key: nav.home -->
+<a href="/" data-i18n="nav.home">Home</a>
+```
+
+The `data-i18n` attribute tells i18next which translation to use.
+
+### 2. Tool Definitions
+
+Tool names and descriptions are defined in `src/js/config/tools.ts` and use a special namespace:
+
+```typescript
+{
+  name: 'Merge PDF',  // Used for shortcuts only
+  subtitle: 'Combine multiple PDFs into one file.',
+}
+```
+
+In translations:
+
+```json
+{
+  "tools": {
+    "mergePdf": {
+      "name": "PDF zusammenführen",
+      "subtitle": "Mehrere PDFs in eine Datei kombinieren."
+    }
+  }
+}
+```
+
+### 3. Dynamic JavaScript (`t()` function)
+
+For translations that need to be applied dynamically:
+
+```typescript
+import { t } from './i18n/i18n';
+
+const message = t('alert.error');
+console.log(message); // "Error" or "Fehler" depending on language
+```
+
+### 4. Placeholders
+
+For input placeholders:
+
+```html
+<input
+  type="text"
+  placeholder="Search for a tool..."
+  data-i18n-placeholder="tools.searchPlaceholder"
+/>
+```
+
+In `common.json`:
+
+```json
+{
+  "tools": {
+    "searchPlaceholder": "Nach einem Tool suchen..."
+  }
+}
+```
+
+---
+
+## Testing Your Translations
+
+### Manual Testing
+
+1. **Start development server:**
+
+   ```bash
+   npm run dev
+   ```
+
+2. **Visit each language:**
+   - English: `http://localhost:5173/en/`
+   - German: `http://localhost:5173/de/`
+   - Vietnamese: `http://localhost:5173/vi/`
+   - Indonesian: `http://localhost:5173/id/`
+   - Chinese: `http://localhost:5173/zh/`
+   - Traditional Chinese (Taiwan): `http://localhost:5173/zh-TW/`
+   - French: `http://localhost:5173/fr/`
+   - Your new language: `http://localhost:5173/es/`
+
+3. **Check these pages:**
+   - Homepage (`/`)
+   - About page (`/about.html`)
+   - Contact page (`/contact.html`)
+   - FAQ page (`/faq.html`)
+   - Tool pages (e.g., `/merge-pdf.html`)
+
+4. **Test these interactions:**
+   - Click the language switcher in the footer
+   - Navigate between pages
+   - Open the settings modal (click gear icon next to search)
+   - Try a tool to see upload messages
+
+### Automated Checks
+
+Check for missing translations:
+
+```bash
+# This will show any missing keys
+node scripts/check-translations.js
+```
+
+_(If this script doesn't exist, you may need to create it or manually compare JSON files)_
+
+### Browser Testing
+
+Test in different browsers:
+
+- Chrome/Edge
+- Firefox
+- Safari
+
+---
+
+## Translation Guidelines
+
+### 1. Keep the Tone Consistent
+
+BentoPDF is **friendly, clear, and professional**. Match this tone in your translations.
+
+✅ **Good:**
+
+```json
+"hero.title": "Ihr kostenloses und sicheres PDF-Toolkit"
+```
+
+❌ **Too formal:**
+
+```json
+"hero.title": "Ihr gebührenfreies und gesichertes Werkzeug für PDF-Dokumente"
+```
+
+### 2. Preserve Formatting
+
+Some strings contain HTML or special characters:
+
+```json
+{
+  "faq.analytics.answer": "We care about your privacy. BentoPDF does not track personal information. We use <a href=\"https://simpleanalytics.com\" class=\"text-indigo-400 hover:underline\" target=\"_blank\" rel=\"noopener noreferrer\">Simple Analytics</a> solely to see anonymous visit counts."
+}
+```
+
+When translating, **keep the HTML tags intact**:
+
+```json
+{
+  "faq.analytics.answer": "Wir schätzen Ihre Privatsphäre. BentoPDF verfolgt keine persönlichen Informationen. Wir verwenden <a href=\"https://simpleanalytics.com\" class=\"text-indigo-400 hover:underline\" target=\"_blank\" rel=\"noopener noreferrer\">Simple Analytics</a> ausschließlich, um anonyme Besucherzahlen zu sehen."
+}
+```
+
+### 3. Handle Plurals and Gender
+
+If your language has complex plural rules or gender distinctions, consult the [i18next pluralization guide](https://www.i18next.com/translation-function/plurals).
+
+Example:
+
+```json
+{
+  "pages": "page",
+  "pages_plural": "pages"
+}
+```
+
+### 4. Don't Translate Brand Names or Legal Terms
+
+Keep these as-is:
+
+- BentoPDF
+- PDF
+- GitHub
+- Discord
+- Chrome, Firefox, Safari, etc.
+- Terms and Conditions
+- Privacy Policy
+- Licensing
+
+### 5. Technical Terms
+
+For technical terms, use commonly accepted translations in your language:
+
+- "Merge" → "Fusionner" (French), "Zusammenführen" (German)
+- "Split" → "Diviser" (French), "Teilen" (German)
+- "Compress" → "Compresser" (French), "Komprimieren" (German)
+
+If unsure, check how other PDF tools translate these terms in your language.
+
+### 6. String Length
+
+Some UI elements have limited space. Try to keep translations **similar in length** to the English version.
+
+If a translation is much longer, test it visually to ensure it doesn't break the layout.
+
+---
+
+## Common Issues
+
+### Issue: Translations Not Showing Up
+
+**Solution:**
+
+1. Clear your browser cache
+2. Hard refresh (Ctrl+F5 or Cmd+Shift+R)
+3. Check browser console for errors
+4. Verify the JSON file is valid (no syntax errors)
+
+### Issue: Some Text Still in English
+
+**Possible causes:**
+
+1. Missing translation key in your language file
+2. Missing `data-i18n` attribute in HTML
+3. Hardcoded text in JavaScript
+
+**Solution:**
+
+- Compare your language file with `en/common.json` to find missing keys
+- Search the codebase for hardcoded strings
+
+### Issue: JSON Syntax Error
+
+**Symptoms:**
+
+```
+SyntaxError: Unexpected token } in JSON at position 1234
+```
+
+**Solution:**
+
+- Use a JSON validator: https://jsonlint.com/
+- Common mistakes:
+  - Trailing comma after last item
+  - Missing or extra quotes
+  - Unescaped quotes inside strings (use `\"`)
+
+### Issue: Language Switcher Not Showing New Language
+
+**Solution:**
+Make sure you added the language to both arrays in `i18n.ts`:
+
+```typescript
+export const supportedLanguages = ['en', 'de', 'es', 'fr', 'zh', 'vi']; // ← Add here
+export const languageNames = {
+  en: 'English',
+  de: 'Deutsch',
+  es: 'Español',
+  fr: 'Français', // ← And here
+  zh: '中文',
+  vi: 'Tiếng Việt',
+};
+```
+
+### Issue: 404 Error When Accessing Language Pages
+
+**Symptoms:**
+Visiting `http://localhost:5173/ja/about.html` shows a 404 error page.
+
+**Solution:**
+You need to add your language code to `SUPPORTED_LANGUAGES` in `vite.config.ts`:
+
+```typescript
+const SUPPORTED_LANGUAGES = [
+  'en',
+  'de',
+  'es',
+  'zh',
+  'zh-TW',
+  'vi',
+  'it',
+  'id',
+  'tr',
+  'fr',
+  'pt',
+  'ja',
+] as const;
+```
+
+After updating, restart the dev server:
+
+```bash
+npm run dev
+```
+
+---
+
+## File Checklist
+
+When adding a new language, make sure these files are updated:
+
+- [ ] `public/locales/{lang}/common.json` - Main translation file
+- [ ] `public/locales/{lang}/tools.json` - Tools translation file
+- [ ] `src/js/i18n/i18n.ts` - Add to `supportedLanguages` and `languageNames`
+- [ ] `vite.config.ts` - Add to `SUPPORTED_LANGUAGES` array
+- [ ] Test all pages: homepage, about, contact, FAQ, tool pages
+- [ ] Test settings modal and shortcuts
+- [ ] Test language switcher in footer
+- [ ] Verify URL routing works (`/{lang}/`)
+- [ ] Run `npm run build` and verify `dist/{lang}/` folder is created
+- [ ] Test that all tools load correctly
+
+---
+
+## Getting Help
+
+If you have questions or need help:
+
+1. Check existing translations in `public/locales/de/common.json` for reference
+2. Open an issue on [GitHub](https://github.com/alam00000/bentopdf/issues)
+3. Join our [Discord server](https://discord.gg/Bgq3Ay3f2w)
+
+---
+
+## Contributing Your Translation
+
+Once you've completed a translation:
+
+1. **Test thoroughly** (see [Testing Your Translations](#testing-your-translations))
+2. **Fork the repository** on GitHub
+3. **Create a new branch**: `git checkout -b add-french-translation`
+4. **Commit your changes**: `git commit -m "Add French translation"`
+5. **Push to your fork**: `git push origin add-french-translation`
+6. **Open a Pull Request** with:
+   - Description of the language added
+   - Screenshots showing the translation in action
+   - Confirmation that you've tested all pages
+
+Thank you for contributing to BentoPDF! 🎉
+
+---
+
+## Translation Progress
+
+Current translation coverage:
+
+| Language            | Code    | Status         | Maintainer |
+| ------------------- | ------- | -------------- | ---------- |
+| English             | `en`    | ✅ Complete    | Core team  |
+| German              | `de`    | ✅ Complete    | Community  |
+| Spanish             | `es`    | ✅ Complete    | Community  |
+| French              | `fr`    | ✅ Complete    | Community  |
+| Italian             | `it`    | ✅ Complete    | Community  |
+| Portuguese          | `pt`    | ✅ Complete    | Community  |
+| Turkish             | `tr`    | ✅ Complete    | Community  |
+| Vietnamese          | `vi`    | ✅ Complete    | Community  |
+| Indonesian          | `id`    | ✅ Complete    | Community  |
+| Chinese             | `zh`    | ✅ Complete    | Community  |
+| Traditional Chinese | `zh-TW` | ✅ Complete    | Community  |
+| Your Language       | `??`    | 🚧 In Progress | You?       |
+
+---
+
+**Last Updated**: January 2026