mirror of https://github.com/johannesjo/super-productivity.git synced 2026-07-17 16:37:43 +00:00

Johannes Millan b6b51707d3 docs: clean up and organize project documentation

- Remove outdated feature requests from .github/CONTRIBUTING.md (GitLab
  support already exists) and add commit message format section
- Improve PR template with type-of-change checkboxes and checklist
- Update commit guideline links in README and CONTRIBUTING.md to
  reference the project's own format instead of external angular.js docs
- Add "only edit en.json" rule to TRANSLATING.md and clarify workflow
- Update add-new-integration.md provider list to match codebase (add
  Trello, ClickUp, Linear, Azure DevOps, Nextcloud Deck; note GitHub
  plugin migration; fix type name to BuiltInIssueProviderKey)
- Add cross-references between mac certificate docs and remove 240-line
  duplicate section from update-mac-certificates.md
- Clean up update-android-app.md (specify npm version args, collapse
  deprecated workflow, translate German UI labels to English)
- Add context to howto-refresh-snap-credentials.md
- Fix fine-grained token note in github-access-token-instructions.md
- Fix absolute URL to relative path in gitlab-access-token-instructions.md
- Fix grammar in i18n-script-usage.md
- Add status headers to all 19 long-term plan files (Planned, Completed,
  Archived with reason, Investigation Complete)
- Fix broken relative link in hybrid-manifest-architecture.md
- Delete supersync-scenarios-simplified.md (duplicate of
  supersync-scenarios.md; known issues already covered there)
- Rename vector-clock-pruning-research.md to
  vector-clock-history-and-alternatives.md for clarity

2026-03-10 10:22:56 +01:00

2.7 KiB

Raw Blame History

I18n Translation Management Script

This document describes the usage of the tools/add-missing-i18n-variables.js script, which helps manage internationalization (i18n) files for Super Productivity.

Overview

The script manages translation files located in src/assets/i18n/. The base language is English (en.json), and other languages like de.json (German), tr.json (Turkish), etc., contain translations.

The script supports three modes:

Extract mode: Creates work-in-progress (WIP) files with missing translations for a specific language.
Merge mode: Merges translated WIP files back into the main language file.
Legacy mode: Adds missing keys to all language files (default when no mode is specified).

File Structure

en.json: The reference English file with all keys.
{lang}.json: Main translation files (e.g., de.json, tr.json).
{lang}-wip.json: Temporary work-in-progress files containing only missing translations.

Usage

Extract Missing Translations

To extract missing translations for a specific language (e.g., Turkish):

node tools/add-missing-i18n-variables.js extract tr

This creates tr-wip.json with all keys that exist in en.json but are missing or empty in tr.json.

Translate WIP File

Edit the generated {lang}-wip.json file and provide translations for the keys.

Example tr-wip.json:

{
  "APP": {
    "SKIP_SYNC_WAIT": "Skip waiting for sync"
  },
  "F": {
    "CALDAV": {
      "ISSUE_CONTENT": {
        "DESCRIPTION": "Description"
      }
    }
  }
}

Merge Translations

After translating the WIP file, merge it back into the main language file:

node tools/add-missing-i18n-variables.js merge tr

This:

Merges translations from tr-wip.json into tr.json
Maintains the same key order as en.json
Validates that all keys are present
Deletes the tr-wip.json file

Legacy Mode (Update All Files)

To add missing keys to all language files at once (preserving existing translations):

node tools/add-missing-i18n-variables.js

This updates all {lang}.json files to include any new keys from en.json, placing them in the same order.

Workflow Example

New features are added, updating en.json with new keys.
Run extract for your language: node tools/add-missing-i18n-variables.js extract de
Translate the keys in de-wip.json.
Run merge: node tools/add-missing-i18n-variables.js merge de
Submit a pull request with the updated de.json.

Notes

The script preserves the order of keys to match en.json.
Empty strings in translation files trigger English fallback.
WIP files are temporary and will be deleted by the merge command.

2.7 KiB Raw Blame History