# Inclusif Plugin Internationalization (i18n)

This document explains how the internationalization system works in the Inclusif WordPress plugin and how to maintain translations.

## Overview

The Inclusif plugin supports multiple languages using WordPress's built-in internationalization (i18n) system. All user-facing strings are wrapped with translation functions and can be translated into different languages.

## Files Structure

```
languages/
├── inclusif.pot          # Template file (Portable Object Template)
├── inclusif-en_US.po     # English translation source
├── inclusif-en_US.mo     # English compiled translation
├── inclusif-es_ES.po     # Spanish translation source
├── inclusif-es_ES.mo     # Spanish compiled translation
└── README.md            # This file
```

## Current Languages

- **English (en_US)** - Full translation
- **Spanish (es_ES)** - Full translation (base language)

## How It Works

1. **Text Domain**: The plugin uses `inclusif` as its text domain
2. **Automatic Loading**: Since WordPress 4.6, translations are loaded automatically by WordPress when needed. This plugin requires WordPress 6.8+ so no manual loading is required.
3. **Functions Used**: All translatable strings use WordPress i18n functions:
   - `__()` - Basic translation
   - `_e()` - Translation with echo
   - `esc_html__()` - Escaped translation
   - `esc_html_e()` - Escaped translation with echo
   - `sprintf()` with `__()` for placeholders

## Adding New Languages

To add a new language (e.g., French - fr_FR):

1. **Create .po file**:

   ```bash
   cp inclusif.pot inclusif-fr_FR.po
   ```

2. **Edit the .po file** header:

   ```po
   "Language: fr_FR\n"
   "Language-Team: French <team@inclusif.life>\n"
   "Plural-Forms: nplurals=2; plural=(n > 1);\n"
   ```

3. **Translate all msgstr entries** in the .po file

4. **Compile to .mo file**:

   ```bash
   msgfmt -o inclusif-fr_FR.mo inclusif-fr_FR.po
   ```

## Updating Translations

When adding new translatable strings to the code:

1. **Extract strings** to update .pot file:

   ```bash
   wp i18n make-pot . languages/inclusif.pot --domain=inclusif
   ```

2. **Update existing .po files**:

   ```bash
   msgmerge --update inclusif-en_US.po inclusif.pot
   msgmerge --update inclusif-es_ES.po inclusif.pot
   ```

3. **Translate new strings** in each .po file

4. **Recompile .mo files**:

   ```bash
   msgfmt -o inclusif-en_US.mo inclusif-en_US.po
   msgfmt -o inclusif-es_ES.mo inclusif-es_ES.po
   ```

## Translation Guidelines

### For Developers

1. **Always use translation functions**:

   ```php
   // Good
   echo esc_html__( 'Settings', 'inclusif' );
   
   // Bad
   echo 'Settings';
   ```

2. **Use placeholders for dynamic content**:

   ```php
   // Good
   printf(
       esc_html__( 'Welcome, %s!', 'inclusif' ),
       esc_html( $username )
   );
   
   // Bad
   echo 'Welcome, ' . $username . '!';
   ```

3. **Add translator comments when needed**:

   ```php
   /* translators: %s: Friend's name */
   __( 'Hello, %s!', 'inclusif' )
   ```

### For Translators

1. **Keep HTML tags in translations**:

   ```po
   msgid "Visit <a href=\"%s\">settings page</a>"
   msgstr "Visita la <a href=\"%s\">página de configuración</a>"
   ```

2. **Preserve placeholders**:

   ```po
   msgid "Hello, %s!"
   msgstr "¡Hola, %s!"
   ```

3. **Consider context and tone**:
   - Match the formality level of the original
   - Use appropriate technical terms
   - Maintain consistency across translations

## Tools and Resources

### Required Tools

- **gettext** - For msgfmt command: `brew install gettext` (macOS)
- **WP-CLI** - For WordPress i18n commands: `wp i18n --help`

### Recommended Tools

- **Poedit** - GUI editor for .po files
- **Loco Translate** - WordPress plugin for online translation
- **WPML** or **Polylang** - For multilingual WordPress sites

### Useful Links

- [WordPress i18n Documentation](https://developer.wordpress.org/apis/handbook/internationalization/)
- [GNU gettext Manual](https://www.gnu.org/software/gettext/manual/)
- [WordPress Coding Standards - i18n](https://developer.wordpress.org/coding-standards/wordpress-coding-standards/php/#internationalization)

## Testing Translations

1. **Change WordPress language**:
   - Go to Settings > General
   - Change "Site Language" to test language
   - Or use `WPLANG` constant in wp-config.php

2. **Use locale switching**:

   ```php
   switch_to_locale( 'es_ES' );
   // Test translated strings
   restore_current_locale();
   ```

3. **Debug translation loading**:

   ```php
   // Add to wp-config.php for debugging
   define( 'WP_DEBUG', true );
   define( 'WP_DEBUG_LOG', true );
   ```

## Best Practices

1. **Regular Updates**: Update translations when adding new features
2. **Consistency**: Use consistent terminology across the plugin
3. **Testing**: Always test translations in actual WordPress environment
4. **Backup**: Keep .po files in version control, .mo files can be regenerated
5. **Documentation**: Document any special translation requirements

## Contributing Translations

To contribute translations:

1. Fork the repository
2. Add your language files following the naming convention
3. Test thoroughly in WordPress environment
4. Submit a pull request with your translations
5. Include information about the language and region

For questions about translations, please contact: <team@inclusif.life>