Shadowbroker/CONTRIBUTING.md

# Contributing to Shadowbroker

Thank you for taking the time to contribute. This document covers things specific to this project — for general open-source contribution etiquette, see the GitHub docs.

---

## Code contributions

1. Fork the repo on GitHub (`bigbodycobain/Shadowbroker`) or GitLab (`bigbodycobain/Shadowbroker` mirror).
2. Make your changes on a feature branch.
3. Run the local test suite:
   - Backend: `pytest backend/tests/`
   - Frontend: `cd frontend && npx vitest run`
4. Open a Pull Request against `main`.

CI runs on every PR. If CI fails, that's blocking — please push fixes rather than asking for it to be merged anyway.

---

## Reporting security issues

Do **not** file security issues as public GitHub issues. Email the maintainer or use a private security advisory on GitHub. Public disclosure of an exploitable vulnerability without prior coordination will be rejected from the project.

---

## Translation contributions

Shadowbroker supports UI localization (`frontend/src/i18n/`). Translation contributions are welcome but held to a stricter standard than most code changes, because translations can subtly reshape user perception in ways that are hard to spot during review. Read this section before submitting one.

### The neutrality requirement

**Translations must be technically faithful to the English source.** That means:

- Each `t('key')` entry should mean approximately the same thing in the target language as in English, modulo idiom.
- Technical terms with established meanings (e.g. "GPS jamming," "military flight," "Tor," "onion routing," "encryption") should be translated using the corresponding established technical term in the target language — **not** softened, rebranded, or politically reframed.
- The set of UI strings should be **the same** between languages. Don't omit features from one locale that are visible in another.

### What will get a translation PR rejected

Translation choices that align the project with the framing or terminology of state propaganda — from **any** country — will be rejected. This applies symmetrically:

| Country / source | Examples of substitutions we will reject |
|---|---|
| **PRC / CCP** | Calling Taiwan a "province" or "renegade province"; reframing protest layers as "riots"; using softened or euphemistic terms for surveillance, internment, or jamming when the source text is direct |
| **Russia** | Calling the Ukraine war a "special military operation"; relabeling occupied territories as Russian; softening sanctions/jamming/disinfo terminology |
| **United States / EU** | Reframing adversaries with editorial labels not in the source (e.g. inserting "regime" where the English says "government"); applying labels like "terrorist" or "rogue state" to entities the English source describes neutrally |
| **Israel / Palestine / any active conflict** | Substituting one side's preferred terminology when the source uses the other side's or a neutral term |
| **Any government** | Adding political slogans, omitting features that government finds inconvenient, or inserting terminology associated with a specific political faction |

The test is **"would a translator working strictly from the English source produce this rendering?"** If the answer requires assuming a political stance the source does not take, the substitution does not belong in the translation.

### How translation PRs are reviewed

Changes to `frontend/src/i18n/**` are owned by the maintainer (see `CODEOWNERS`) and require explicit approval. We will:

1. Diff the translation against the English source key-by-key.
2. Spot-check a sample of entries with a native speaker of the target language when possible.
3. Look for the patterns above.
4. Look for suspicious additions to the i18n infrastructure itself (e.g. a remote translation fetcher, telemetry on language choice) — the i18n layer is supposed to be 100% client-side static JSON.

A PR that adds a new language is harder to review than one that fixes typos in an existing language. For new languages, please be patient and expect a real review window. For typo fixes, please describe each change in the PR body so the reviewer can verify intent.

### What about adding a new language?

We welcome new languages. The mechanical setup is documented in the header comment of `frontend/src/i18n/index.tsx`. Beyond that:

- Register the locale in `backend/services/telegram_translate.py` (`_LOCALE_TO_GOOGLE` and `_SOURCE_LANG_LABELS`) and the matching fallback labels in `frontend/src/components/MaplibreViewer/popups/TelegramOsintPopup.tsx`. Simple codes like `fa` already pass through to Google Translate, but without the labels the UI shows raw codes (e.g. `FA`) for source language, and aliases like `zh` → `zh-CN` need an explicit map entry.
- For RTL languages, add the locale to `RTL_LOCALES` in `frontend/src/i18n/index.tsx` and smoke-test the map chrome (sidebar, modals, popups) with that locale selected — `dir="rtl"` can mirror flex layouts that were designed LTR.
- We are more likely to merge a new language quickly if at least one reviewer in the maintainer's network speaks it.
- If you are the *only* speaker of the target language reading this repo, your translation is welcome but the merge timeline will be longer while a reviewer is found.
- Partial translations are fine — the system falls back to English for any missing key.

---

## Anything else

If you have a question that isn't a security report, opening a GitHub Discussion or a draft PR with a question in the body is the fastest way to get a response. Direct emails are read but not always replied to promptly.