# Translation Guide for Maintenance Reports by webcycle

This guide explains how to create and manage translation files for this plugin.

## Directory Structure

Translation files should be placed in:
```
/languages/
  ├── maintenance-reports-by-webcycle.pot  (Template file - generated)
  ├── maintenance-reports-by-webcycle-en_US.po  (English - optional)
  ├── maintenance-reports-by-webcycle-en_US.mo  (Compiled English)
  ├── maintenance-reports-by-webcycle-es_ES.po  (Spanish translation)
  ├── maintenance-reports-by-webcycle-es_ES.mo  (Compiled Spanish)
  └── ... (other language files)
```

## Method 1: Using WP-CLI (Recommended)

If you have WP-CLI installed, this is the easiest method:

```bash
cd /path/to/wp-content/plugins/maintenance-reports-by-webcycle
wp i18n make-pot . languages/maintenance-reports-by-webcycle.pot --domain=maintenance-reports-by-webcycle --skip-js
```

This command will:
- Scan all PHP files in the plugin
- Extract all translatable strings
- Create a `.pot` file in the languages directory

## Method 2: Using Poedit (GUI Tool)

1. **Download Poedit** (https://poedit.net/)
2. **Create New Translation**
   - File → New → Translation from POT file
   - Select or create `maintenance-reports-by-webcycle.pot`
3. **Extract from Source Code**
   - Catalog → Properties → Sources paths: Add the plugin root directory
   - Catalog → Properties → Sources keywords: WordPress standard keywords are already set
   - Catalog → Extract from Sources
4. **Save the .pot file** to `/languages/` directory

## Method 3: Using gettext Tools (Command Line)

### Step 1: Extract strings using xgettext

```bash
cd /path/to/wp-content/plugins/maintenance-reports-by-webcycle

xgettext \
  --language=PHP \
  --keyword=__ \
  --keyword=_e \
  --keyword=esc_html__ \
  --keyword=esc_html_e \
  --keyword=esc_attr__ \
  --keyword=esc_attr_e \
  --keyword=_x \
  --keyword=_ex \
  --keyword=_n \
  --keyword=_nx \
  --keyword=wp_nonce_field \
  --from-code=UTF-8 \
  --output=languages/maintenance-reports-by-webcycle.pot \
  --msgid-bugs-address="your-email@example.com" \
  --copyright-holder="webcycle" \
  --package-name="Maintenance Reports by webcycle" \
  *.php
```

### Step 2: Edit the .pot file header

Open the `.pot` file and update the header:

```
msgid ""
msgstr ""
"Project-Id-Version: Maintenance Reports by webcycle 1.0.0\n"
"Report-Msgid-Bugs-To: https://webcycle.ai/\n"
"POT-Creation-Date: 2024-01-01 12:00+0000\n"
"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
"Language-Team: LANGUAGE <LL@li.org>\n"
"Language: \n"
"MIME-Version: 1.0\n"
"Content-Type: text/plain; charset=UTF-8\n"
"Content-Transfer-Encoding: 8bit\n"
"Plural-Forms: nplurals=INTEGER; plural=EXPRESSION;\n"
```

## Creating Translation Files (.po)

### For a Specific Language (e.g., Spanish - es_ES)

1. **Copy the .pot file**:
```bash
cp languages/maintenance-reports-by-webcycle.pot languages/maintenance-reports-by-webcycle-es_ES.po
```

2. **Edit the header** in the `.po` file:
```
"Language: es_ES\n"
"Plural-Forms: nplurals=2; plural=(n != 1);\n"
```

3. **Translate the strings** using Poedit or a text editor:
   - `msgid` = English source string
   - `msgstr` = Translated string

### Example Translation Entry:

```
#: maintenance-reports-by-webcycle.php:163
msgid "Dashboard"
msgstr "Panel de Control"
```

## Compiling .po to .mo Files

WordPress uses compiled `.mo` files (binary format) for faster loading.

### Method 1: Using Poedit
Poedit automatically compiles `.mo` files when you save.

### Method 2: Using msgfmt (Command Line)
```bash
msgfmt -o languages/maintenance-reports-by-webcycle-es_ES.mo languages/maintenance-reports-by-webcycle-es_ES.po
```

### Method 3: Using WP-CLI
```bash
wp i18n make-mo languages/
```

## Language Codes Reference

Common language codes:
- English (US): `en_US`
- Spanish (Spain): `es_ES`
- French (France): `fr_FR`
- German (Germany): `de_DE`
- Italian (Italy): `it_IT`
- Portuguese (Brazil): `pt_BR`
- Dutch (Netherlands): `nl_NL`
- Japanese (Japan): `ja`
- Chinese (Simplified): `zh_CN`

## Testing Translations

1. **Install the translation**:
   - Copy `.po` and `.mo` files to `/languages/` directory
   - Or use WordPress's translation system at `/wp-content/languages/plugins/`

2. **Change WordPress language**:
   - Settings → General → Site Language
   - Or use a plugin like "Loco Translate"

3. **View the plugin**:
   - All translatable strings should appear in the selected language

## Submitting Translations

If you want to contribute translations:

1. **WordPress.org**: Submit via https://translate.wordpress.org/
2. **Include in plugin**: Submit via GitHub/Pull Request with:
   - `.po` file
   - `.mo` file (or we can compile it)

## Plural Forms Reference

Different languages have different plural rules. Common examples:

- **English**: `nplurals=2; plural=(n != 1);`
- **Spanish**: `nplurals=2; plural=(n != 1);`
- **French**: `nplurals=2; plural=(n > 1);`
- **Russian**: `nplurals=3; plural=(n%10==1 && n%100!=11 ? 0 : n%10>=2 && n%10<=4 && (n%100<10 || n%100>=20) ? 1 : 2);`

For more info: https://translate.wordpress.org/projects/wp/dev/

## Quick Start Command Summary

```bash
# 1. Generate .pot file
wp i18n make-pot . languages/maintenance-reports-by-webcycle.pot --domain=maintenance-reports-by-webcycle

# 2. Create Spanish translation
cp languages/maintenance-reports-by-webcycle.pot languages/maintenance-reports-by-webcycle-es_ES.po

# 3. Edit es_ES.po with Poedit and translate

# 4. Compile to .mo
wp i18n make-mo languages/

# Or manually:
msgfmt -o languages/maintenance-reports-by-webcycle-es_ES.mo languages/maintenance-reports-by-webcycle-es_ES.po
```