mirror of https://github.com/fccview/cronmaster.git synced 2025-12-23 14:08:43 -05:00

Files

fccview 1b6f5b6e34 fix minor styling, allow custom translations and prepare for release

2025-11-13 15:11:49 +00:00

10 KiB

Raw Permalink Blame History

Translation Guide

CronMaster supports internationalization (i18n) with both unofficial custom translations and official translations that can be contributed to the project.

Custom User Translations (Unofficial)
Official Translations via Pull Request
Translation File Structure
Testing Your Translations
Translation Guidelines

Custom User Translations (Unofficial)

You can create your own translation files locally without modifying the source code. These translations are loaded from the ./data/translations/ directory.

Quick Setup

Create the translations directory:
```
mkdir -p ./data/translations
```
Copy a template:
```
cp app/_translations/en.json ./data/translations/your-locale.json
```
Note: for docker users, you can copy the translation template from the source code
Set your locale:
```
export LOCALE=your-locale
```

Step-by-Step Guide

1. Prepare the Directory Structure

# Create translations directory in your data folder
mkdir -p ./data/translations

# Verify the structure
ls -la ./data/translations/

2. Create Your Translation File

Use English as a template and create your locale file:

# Copy English template
cp app/_translations/en.json ./data/translations/fr.json

# Or for any other locale
cp app/_translations/en.json ./data/translations/es.json
cp app/_translations/en.json ./data/translations/de.json

3. Edit Your Translation

Open your translation file and modify the values:

# Edit with your preferred editor
nano ./data/translations/fr.json
# or
code ./data/translations/fr.json

4. Configure Environment

Set the LOCALE environment variable to your locale code:

# For French
export LOCALE=fr

# For Spanish
export LOCALE=es

# For German
export LOCALE=de

5. Restart the Application

Restart CronMaster to load the new translations:

# If running with npm/yarn
npm restart
# or
yarn restart

# If using Docker
docker-compose restart cronmaster

Translation Priority

Translations are loaded in this order:

Custom: ./data/translations/{locale}.json (highest priority)
Built-in: app/_translations/{locale}.json
Fallback: app/_translations/en.json (English)

This means you can override any built-in translation by creating a custom file with the same locale code.

Official Translations via Pull Request

To contribute an official translation to the CronMaster project, you'll need to create a pull request targeting the develop branch. All feature contributions, including translations, are merged into develop first before being released to main.

Important: Do not target the main branch directly. All pull requests should be made against develop.

Prerequisites

Basic knowledge of Git and GitHub
Understanding of JSON format
Familiarity with the CronMaster interface
Accuracy in translation

Step-by-Step Contribution Process

1. Fork the Repository

# Fork the repository on GitHub
# Visit: https://github.com/fccview/cronmaster
# Click "Fork" button in the top right

2. Clone Your Fork

# Clone your fork locally
git clone https://github.com/YOUR_USERNAME/cronmaster.git
cd cronmaster

# Add upstream remote
git remote add upstream https://github.com/fccview/cronmaster.git

3. Create a Feature Branch

# First, ensure you're on the develop branch
git checkout develop
git pull upstream develop

# Then create and switch to a new feature branch
git checkout -b feature/add-locale-XX

# Example for Spanish:
git checkout develop
git pull upstream develop
git checkout -b feature/add-locale-es

# Example for French:
git checkout develop
git pull upstream develop
git checkout -b feature/add-locale-fr

4. Create the Translation File

# Copy the English template
cp app/_translations/en.json app/_translations/LOCALE.json

# Replace LOCALE with your locale code (e.g., es, fr, de, it, pt, etc.)
cp app/_translations/en.json app/_translations/es.json

5. Translate the Content

Open your translation file and translate all values:

# Edit the translation file
nano app/_translations/es.json
# or
code app/_translations/es.json

Important: Do not change the JSON keys, only translate the string values.

6. Test Your Translation

# Set your locale for testing
export LOCALE=es

# Start the development server
npm run dev
# or
yarn dev

# Visit http://localhost:3000 and verify translations

7. Commit Your Changes

# Add your translation file
git add app/_translations/es.json

# Commit with a descriptive message
git commit -m "feat: add Spanish (es) translation

- Complete Spanish translation for all UI strings
- Tested with LOCALE=es environment variable
- Follows translation guidelines and structure"

8. Push to Your Fork

# Push your branch to GitHub
git push origin feature/add-locale-es

9. Create a Pull Request

Visit your fork on GitHub
Click "Compare & pull request" for your branch
Important: Ensure the pull request targets the develop branch (not main)
- The "base repository" should be fccview/cronmaster
- The "base" branch should be develop
- The "head repository" should be YOUR_USERNAME/cronmaster
- The "compare" branch should be feature/add-locale-XX
Fill out the pull request template:

Title: feat: add Spanish (es) translation

Description:

## Description

This PR adds official Spanish translation support to CronMaster.

## Changes

- Added `app/_translations/es.json` with complete Spanish translations
- All UI strings have been translated accurately
- Translation structure matches the English template

## Testing

- Tested with `LOCALE=es` environment variable
- Verified all pages and components display correctly
- No broken translations or missing keys

## Checklist

- [x] Translation is complete (all keys translated)
- [x] No JSON syntax errors
- [x] Follows translation guidelines
- [x] Tested in development environment
- [x] Commit message follows conventional format

10. Address Review Feedback

The maintainers may request changes. Make any necessary updates:

# Make changes based on feedback
git add app/_translations/es.json
git commit -m "fix: update Spanish translations based on review feedback"
git push origin feature/add-locale-es

Pull Request Requirements

Your pull request must meet these criteria:

Complete Translation: All keys from en.json must be translated
Valid JSON: No syntax errors, proper escaping
Accurate Translation: Professional, accurate translations
Consistent Terminology: Use consistent terms throughout
Cultural Adaptation: Adapt content appropriately for the locale
Tested: Verified working in the application
Proper Commit: Follows conventional commit format

Translation Standards

Use proper grammar and punctuation
Maintain consistent terminology
Keep technical terms in English when appropriate
Use appropriate formality level for the target language
Consider cultural context and conventions
Keep translations concise but complete

Translation File Structure

All translation files follow this JSON structure:

{
  "common": {
    "cronManagementMadeEasy": "Cron Management made easy",
    "user": "User",
    "cancel": "Cancel",
    "close": "Close"
  },
  "cronjobs": {
    "cronJobs": "Cron Jobs",
    "scheduledTasks": "Scheduled Tasks"
  },
  "scripts": {
    "bashScripts": "Bash Scripts"
  }
}

Key Guidelines

Keys remain unchanged: Never modify the JSON keys
Values are translated: Only translate the string values
Hierarchy preserved: Maintain the nested object structure
Data types maintained: Keep arrays as arrays, objects as objects

Testing Your Translations

Development Testing

# Set your locale
export LOCALE=your-locale

# Start development server
npm run dev

# Test all pages and features:
# - Main dashboard
# - Cron job management
# - Script editor
# - Settings pages
# - Error messages
# - Modal dialogs

Docker Testing

# docker-compose.yml
services:
  cronmaster:
    environment:
      - LOCALE=your-locale
    volumes:
      - ./data/translations:/app/data/translations:ro

Validation Checklist

All pages load without errors
No untranslated strings (should show key names if missing)
Text fits within UI components
Pluralization works correctly (if applicable)
Special characters display correctly
Date/time formats are appropriate for locale