Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
132 lines (93 loc) · 5.07 KB

CONTRIBUTING.md

File metadata and controls

132 lines (93 loc) · 5.07 KB

How to Contribute

While we are working on NZBGet project all the time, we still would really like and need help on many areas:

  • Major - code contributions on features and bugs
  • Improvements in tests
  • Improvements on documentation

We entice our users to participate in the project, please don't hesitate to get involved - create a new issue or pull request - that would also greatly help if you'll share your usage experience.

Documentation

Main documentation is available on the NZBGet.com website - https://nzbget.com/documentation/

Development

NZBGet natively supports for multiple platforms and build options, so each platform has their own development documenation, including:

Branches naming policy

  • main is a protected branch that contains only release code
  • develop is a protected branch for development
  • new branches should follow the following convention:
    • hotfix/brief-description for any small hotfixes
    • feature/brief-description for any new developments
    • bugfix/brief-description for bugs

Pull requests flow for develop and main branches

  1. For PRs targeting develop branch Squash and merge mode must be used.
  2. After merging branch to develop, branch must be deleted.
  3. For release PR (develop -> main) Create a merge commit mode must be used.
  4. After merging develop -> main, must be back merge main -> develop before any changes in develop branch.

This flow results to the fact that in the PR to master branch we see only the squashed commits that correspond to the PRs in the develop branch in current release cycle.

Version changes in release cycle

After the release has been published (from the main branch), the minor version in the develop branch should be increased so that subsequent test builds are a higher version than the release.

List of files to change version:

  1. CMakeLists.txt - project block
  2. osx/NZBGet-Info.plist - CFBundleShortVersionString block

WebUI Internationalization (i18n)

The WebUI uses a client-side i18n system with JSON translation files.

File structure

webui/
  locales.source.json              — Source of truth: all translation keys with English text and translator descriptions
  i18n.js                          — Runtime engine: loads translations, applies them via data-i18n attributes
  _locales/
    de/messages.json               — Per-language translation files
    fr/messages.json
    ...

  > **Note:** Files under `_locales/` are auto-generated by the translation
  > management process. Do **not** edit them manually — any changes will be
  > overwritten. All translation work should be done in `locales.source.json`
  > (new keys) or through the translation platform (existing keys).

Adding a new translatable message

  1. Add a data-i18n attribute to the HTML element:

    <span data-i18n="my_new_key"></span>

    For titles, placeholders, values, or HTML content:

    <input data-i18n-title="my_tooltip_key">
<input data-i18n-placeholder="my_placeholder_key">
<div data-i18n-html="my_html_key"></div>

  2. If the message has dynamic parts, use $1, $2 placeholders:

    <span data-i18n="my_key" data-i18n-arg-1="42"></span>

  3. Add the key to webui/locales.source.json:

    "my_new_key": {
  "message": "Default English text with $1 placeholder",
  "description": "Brief description for translators"
}

  4. If the key describes a configuration option (e.g., MainDir), run generate_conf_locales.py to regenerate config_desc_* entries:

    python3 scripts/generate_conf_locales.py nzbget.conf webui/locales.source.json

  5. Translations for non-English languages are managed through an external platform/process and stored in webui/_locales/<code>/messages.json. These files are auto-generated — never edit them directly. Missing keys fall back to English automatically.

Key naming conventions

Prefix Used for
col_ Table column headers
btn_ Button labels
status_ Status labels
label_ General labels and badges
desc_ Descriptions and tooltips
config_desc_ Auto-generated config option descriptions

Use snake_case and keep keys short but descriptive.

How translation loading works

  1. i18n.js loads locales.source.json — English becomes the base translation.
  2. Detects the browser language or reads a saved preference from localStorage.
  3. If non-English, fetches _locales/<code>/messages.json and merges it on top of English.
  4. Calls I18n.translatePage() which scans the DOM for data-i18n attributes and replaces content accordingly.