Esasy mazmuna geç

Ösüş


Ösüş gollanmasy

Diňe iňlis dilindäki faýllary redaktirläň; terjimeler awtomatiki ýaýradylýar

Resminamalary diňe website/docs (iňlisçe) aşagynda täzeläň. website/i18n/<locale>/… aşagyndaky terjimeler awtomatik döredilýär we el bilen redaktirlenmeli däldir. Lokalizirlenen mazmuny täzelemek üçin terjime wezipelerini (mysal üçin, make translate_web_docs_batch) ulanyň.

Deslapky talaplar

  • Node.js 22+ we npm (Node 22 bilen synagdan geçirildi)
  • Thunderbird 128 ESR ýa-da täze (eli bilen synag üçin)

Proýekt gurluşy (ýokary dereje)

  • Kök: gaplama skripti distribution_zip_packer.sh, dokumentler, ekran suratlary
  • sources/: esasy goşundy kody (arka fon, sazlamalar/popup UI, manifestler, nyşanlar)
  • tests/: Vitest toplum
  • website/: Docusaurus dokumentleri (website/i18n/de/... aşagynda i18n bilen)

Gurnama we gurallar

  • Köke degişli baglylyklary gurnamak: npm ci
  • Dokumentler (islege görä): cd website && npm ci
  • Maksatlary görkezmek: make help

Göni işe ösdürmek (web‑ext run)

  • Firefox Desktop-da çalt tekrarlama (diňe UI smoke‑synaglary):
  • npx web-ext run --source-dir sources --target=firefox-desktop
  • Thunderbird-de işletmek (MailExtensions üçin has gowusy):
  • npx web-ext run --source-dir sources --start-url about:addons --firefox-binary "$(command -v thunderbird || echo /path/to/thunderbird)"
  • Maslahatlar:
  • Thunderbird-iň Ýalňyşlyk Konsolyny açyk saklaň (Tools → Developer Tools → Error Console).
  • MV3 çäre sahypalary işjeň bolmadyk wagt togtadylýar; kod üýtgemelerinden soň goşundyny täzeden ýükläň ýa-da web‑ext avtomatiki täzeden ýüklesin.
  • Diňe Firefox‑a degişli käbir häsiýetler başgaça bolup biler; API deňligini tassyklamak üçin hökman Thunderbird‑de barlaň.
  • Thunderbird ikilik ýollary (mysallar):
  • Linux: thunderbird (mysal üçin, /usr/bin/thunderbird)
  • macOS: /Applications/Thunderbird.app/Contents/MacOS/thunderbird
  • Windows: "C:\\Program Files\\Mozilla Thunderbird\\thunderbird.exe"
  • Profil izolýasiýasy: gündelik sazlamalaryňyza täsir etmezlik üçin ösüş üçin aýratyn Thunderbird profili ulanyň.

Make nyşanalary (Alfabet tertibinde)

Makefile umumy ösüş akymlaryny standarlaýar. Her bir nyşana barada bir setirlik gysgaçaça almak üçin islendik wagt make help işlediň.

Maslahat: nyşana görkezilmezden make işledilse, nyşana saýlamak üçin ýönekeý Whiptail menýusy açylýar.

NyşanaBir setirlik beýany
cleanÝerli build/preview artefaktlaryny aýyrmak (tmp/, web-local-preview/, website/build/).
commitFormatlaý, synaglary işledýär (i18n goşmak bilen), üýtgeşmeler gündeligini täzelýär, commit edýär we push edýär.
eslintESLint-i tekiz konfigurasiýa arkaly işledýär (npm run -s lint:eslint).
helpHemmesi boýunça bir setirlik düşündirişli sanaw (tertiplendirilen).
lintweb‑ext lint sources/ üstünde (wagtylaýyn manifest; ZIP-leri äsgermeýär; ölümçül däl).
menuNyşana we islege bagly argumentleri saýlamak üçin interaktiw menýu.
packATN we LOCAL ZIP-leri gurýar (linteri işledýär; gaplaýjy skripti çagyrýar).
prettierRepozitoriýany ýerinde formatlaýar (üýtgeşmeleri ýazýar).
prettier_checkPrettier barlaýyş režiminde (ýazma ýok); gaýtadan format gerek bolsa şowsuz bolýar.
prettier_writeprettier üçin lakam.
testIlki Prettier (ýazma), ESLint, soňra Vitest (eger gurnalansa örtük).
test_i18nDiňe i18n synaglary: goşundy üçin ýer tutujy/paritet + websaýt pariteti.
translate_apptranslation_app üçin lakam.
translation_appProgramma UI setirlerini sources/_locales/en/messages.json-den terjime et.
translate_web_docs_batchWebsaýt dokumentlerini OpenAI Batch API arkaly terjime et (ödretilýär).
translate_web_docs_syncWebsaýt dokumentlerini sinhron ýagdaýda terjime et (miras, non-batch).
translate_web_indextranslation_web_index üçin lakam.
translation_web_indexBaş sahypa/üst menýu/astes UI-ny terjime et (website/i18n/en/code.json → .../<lang>/code.json).
web_buildDokumentleri website/build-e gurýar (--locales / BUILD_LOCALES goldaýar).
web_build_linkcheckOflayn howpsuzlykly baglanyşyk barlagy (daşdaky HTTP[S]-leri geçýär).
web_build_local_previewÝerli gh‑pages öň synanyşygy; 8080–8090 aralygynda awto-serwis; islege görä synaglar/baglanyşyk barlagy.
web_push_githubwebsite/build-i gh-pages şahasyna push et.

Opsionlar üçin sintaksis

  • Opsionlary geçirmek üçin make <command> OPTS="…" ulanyň (dyrnaklar maslahat berilýär). Aşakdaky her nyşana mysal ulanylyşyny görkezýär.

--

Locale gurmak boýunça maslahatlar

  • Locale-laryň bir bölegini gurmak: BUILD_LOCALES="en de" goýuň ýa-da OPTS="--locales en,de"-i web nyşanalaryna geçiriň.
  • Belli bir locale üçin öň synanyşyk: http://localhost:<port>/Thunderbird-Reply-with-Attachments/de/.

Gurmak we gaplamak

  • ZIP-leri gurmak: make pack
  • Repo kökünde ATN we LOCAL ZIP-leri döredýär (artefaktlary el bilen redaktirlemäň)
  • Maslahat: gaplamazdan öň sources/manifest_ATN.json hem-de sources/manifest_LOCAL.json-daky wersiýany täzeläň
  • El bilen gurnama (ösüş): Thunderbird → Tools → Add‑ons and Themes → gear → Install Add‑on From File… → gurlan ZIP-faýly saýlaň

Synag

  • Doly toplum: make test (Vitest)
  • Örtük (islege görä):
  • npm i -D @vitest/coverage-v8
  • make test işlediň; HTML hasabaty üçin coverage/index.html açyň
  • Diňe i18n: make test_i18n (UI açarlary/yer tutujy/titllar + websaýt boýunça her locale/ her dokument pariteti id/title/sidebar_label barlaglary bilen)

Düzediş (debug) we žurnallar

  • Ýalňyşlyk konsoly: Tools → Developer Tools → Error Console
  • Runtime wagtynda giňişleýin žurnallary aç/ýap:
  • Işjeňleşdir: messenger.storage.local.set({ debug: true })
  • Öçür: messenger.storage.local.set({ debug: false })
  • Jogaplary düzýän/iberýän wagtynda žurnallar peýda bolýar

Dokumentler (websaýt)

  • Ösüş serweri: cd website && npm run start
  • Statik saýt gurmak: cd website && npm run build
  • Make deňleştirmeleri (alfabetik): make web_build, make web_build_linkcheck, make web_build_local_preview, make web_push_github
  • Ulanyş mysallary:
  • Diňe EN, synaglary/baglanyşyk barlagyny geç, push ýok: make web_build_local_preview OPTS="--locales en --no-test --no-link-check --dry-run"
  • Hemme locale, synaglar/baglanyşyk barlagy bilen, soňra push: make web_build_local_preview && make web_push_github
  • Çap etmezden öň, oflajn howpsuz baglanyşyk barlagyny işlediň: make web_build_linkcheck.
  • i18n: Iňlisçe website/docs/*.md-de; Nemesçe terjimeler website/i18n/de/docusaurus-plugin-content-docs/current/*.md-de
  • Gözleg: Eger Algolia DocSearch gurşaw üýtgeýjileri CI-de sazlanan bolsa (DOCSEARCH_APP_ID, DOCSEARCH_API_KEY, DOCSEARCH_INDEX_NAME), saýt Algolia gözlegi ulanar; bolmasa ýerli gözlege gaýdyp barar. Baş sahypada gözleg gutusyny açmak üçin / ýa-da Ctrl+K basyň.

  • website/src/pages/donate.js
  • Ugrukdyrma: /donate (we /<locale>/donate)
  • Hereketi:
  • Häzirki ugrukdyrmada locale bar bolsa (mysal üçin, /de/donate), şony ulanyň
  • Ýogsam, navigator.languages bilen sazlanan locale-laryň arasynda iň gowy gabat gelýänini saýlaň; bolmasa deslapky locale-a gaýdyp barýar
  • Aşakdakylara gönükdirýär:
  • en/docs/donation
  • beýlekiler → /<locale>/docs/donation
  • Dogry baseUrl dolandyryşy üçin useBaseUrl ulanylýar
  • Meta täzelenişi + ätiýaçlyk hökmünde noscript baglanyşygy öz içine alýar


Öň synanyşyk boýunça maslahatlar

  • Node öň synanyşygyny arassa duruzmak: http://localhost:<port>/__stop açyň (Local server started-den soň çap edilýär).
  • Suratlar MDX/JSX-de ýüklenmese, saýt baseUrl-e hormat goýmak üçin useBaseUrl('/img/...') ulanyň.
  • Ilki öň synanyşyk başlaýar; baglanyşyk barlagy soňundan işledilýär we päsgelçilik döretmeýär (bozulandyk daşky baglanyşyklar öň synanyşygy duruzmaýar).
  • Mysal öň synanyşyk URL-si: http://localhost:<port>/Thunderbird-Reply-with-Attachments/ (“Local server started” diýeninden soň çap edilýär).
  • Baglanyşyk barlagyndaky daşky baglanyşyklar: Käbir daşky saýtlar (mysal üçin, addons.thunderbird.net) awtomatiki süýrenijileri petikleýär we baglanyşyk barlaglarynda 403 görkezmegi mümkin. Öň synanyşyk şonda-da başlaýar; bulary äsgermezlik etmek howpsuz.

Websaýty terjime etmek

Näme terjime edip bilersiňiz

  • Diňe websaýt UI: baş sahypa, üst menýu, ast menýu we beýleki UI setirleri. Häzirlikçe dokumentleriň mazmuny diňe iňlisçe bolýar.

Nirede redaktirlemeli

  • website/i18n/<locale>/code.json-i redaktirläň (en-i nusga ýaly ulanyň). {year}, {slash}, {ctrl}, {k}, {code1} ýaly ýer tutujylary üýtgetmäň.

Faýllary döretmek ýa-da täzelemek

  • Hemme locale üçin ýetmeýän şablonlary döret: npm --prefix website run i18n:stubs
  • Täze setirleri goşandan soň iňlisçeden şablonlary üstünden ýaz: npm --prefix website run i18n:stubs:force
  • Birek-birek locale üçin alternatiwa: npx --prefix website docusaurus write-translations --locale <locale>

Baş sahypa/üst/ast menýu UI setirlerini terjime etmek (OpenAI)

  • Bir gezek ygtyýarnamalary goýuň (shell ýa-da .env):
  • export OPENAI_API_KEY=sk-...
  • Islege görä: export OPENAI_MODEL=gpt-4o-mini
  • Bir gezeklik (hemmesi, en-i geç): make translate_web_index
  • Belli locale-lar bilen çäklendir: make translate_web_index OPTS="--locales de,fr"
  • Bar bolan bahalary üstünden ýaz: make translate_web_index OPTS="--force"

Barlag we gaýtadan synanyşyklar

  • Terjime skripti JSON gurluşyny barlaýar, gyrk yzygiderli ýaý bilen ýer tutujylary saklaýar we URL-leriň üýtgemeýändigini üpjün edýär.
  • Barlag şowsuz bolsa, bar bolan bahalary saklamazdan öň 2 gezekçe çenli gaýtadan synanyşýar we düşündiriş berýär.

Localeňizi öň synanyşyň

  • Ösüş serweri: npm --prefix website run start
  • http://localhost:3000/<locale>/Thunderbird-Reply-with-Attachments/-e gidiň

Ibermek

  • Redaktirlenen code.json faýl(lar)y bilen PR açyň. Üýtgeşmeleri fokusda saklaň we mümkin bolsa çalt skrinşot goşuň.

Howpsuzlyk we Konfigurasiýa maslahatlary

  • sources/manifest.json-i commit etmäň (gurluş tarapyndan wagtlaýyn döredilýär)
  • Täzeleniş kanaly saklansyn üçin browser_specific_settings.gecko.id durnukly saklaň

Sazlamalaryň durnuklylygy

  • Saklamak: Ulanyjynyň ähli sazlamalary storage.local-de saklanýar we goşundy täzelenmeleri boýunça durnukly bolýar.
  • Gurnama: Deslapkylar diňe açar doly ýok (undefined) bolanda ulanylýar.
  • Täzelenme: Migrasiýa diňe ýok açarlary doldurýar; bar bolan bahalar asla üstünden ýazylmaýar.
  • Shema belligi: settingsVersion (häzirki wagtda 1).
  • Açarlar we deslapkylar:
  • blacklistPatterns: string[]['*intern*', '*secret*', '*passwor*']
  • confirmBeforeAdd: booleanfalse
  • confirmDefaultChoice: 'yes'|'no''yes'
  • warnOnBlacklistExcluded: booleantrue
  • Kod: sources/background.jsinitializeOrMigrateSettings() we SCHEMA_VERSION-e serediň.

Ösüş akymy (täze sazlama goşmak)

  • sources/background.js-de SCHEMA_VERSION-i artdyryň.
  • Täze açar + deslapky bahany initializeOrMigrateSettings()-däki DEFAULTS obýektine goşuň.
  • Deslapkyları sepmekde “diňe-undefined bolsa” düzgünini ulanyň; bar bolan bahalary üstünden ýazmaň.
  • Eger sazlama ulanyja görünýän bolsa, sources/options.js-de baglanyşyklary ediň we lokalizirlenen setirleri goşuň.
  • Synaglary goşuň/saýlaň (tests/background.settings.migration.test.js-e serediň).

El bilen synag maslahatlary

  • Täze gurnamany simulirlemek: giňeltmäniň maglumat katalogyny arassalaň ýa-da täze profil bilen başlaň.
  • Täzelenmäni simulirlemek: storage.local-de settingsVersion-i 0 edip goýuň we täzeden ýükläň; bar bolan bahalaryň üýtgemeýändigini we diňe ýok açarlaryň goşulandygyny tassyklaň.

Näsazlyklary düzetmek

  • Thunderbird-iň 128 ESR ýa-da täze boldugyna göz ýetiriň
  • Runtime meseleleri üçin Ýalňyşlyk konsolyny ulanyň
  • Eger saklanan sazlamalar dogry ulanylmaýan ýaly bolsa, Thunderbird-i täzeden işe girizip gaýtadan synanyşyň. (Thunderbird sessiýalar arasynda ýagdaýy keşiňde saklap biler; täzeden işe girizmek täze sazlamalaryň ýüklenmegini üpjün eder.)

CI we Örtük

  • GitHub Actions (CI — Tests) vitest-i örtük eşiklandyryşlari bilen işledýär (setirleriň/funksiýalaryň/şahalaryň/beýannamalaryň 85%-i). Eşiklandyryşlara ýetilmese, iş şowsuz bolýar.
  • Aýlaw (workflow) HTML hasabaty bilen coverage-html atly artefakty ýükläp goýýar; ony işlediş sahypasyndan ýükläp alyň (Actions → iň soňky işlediş → Artifacts).

Goşant goşmak

  • Şaham/commit/PR düzgünleri üçin CONTRIBUTING.md göriň
  • Maslahat: gündelik profiliňize täsir etmezlik üçin synaglar üçin aýratyn Thunderbird ösüş profilini dörediň.

Terjimeler

  • Uly “hemmesi → hemmesi” terjime işlerini işletmek haýal we gymmat bolup biler. Ilki bölekden başlaň (mysal üçin, birnäçe dokument we 1–2 locale), netije barlaň, soň giňeldiň.

  • Gaýtadan synanyşyk syýasaty: terjime işleri API ýalňyşlarynda üsti-üçin ýokarlanýan yza çekiş bilen 3 gezekçe çenli gaýtadan synanyşyk edýär; scripts/translate_web_docs_batch.js we scripts/translate_web_docs_sync.js-e serediň.

Dokumentler üçin skrinşotlar

  • Suratlary website/static/img/ aşagynda saklaň.

  • Olara MD/MDX-de useBaseUrl('/img/<filename>') arkaly salgylanyň, şonda ýollar saýt baseUrl bilen işleýär.

  • website/static/img/ aşagynda suratlary goşandan ýa-da adyny üýtgedenden soň, ähli salgylaryň henizem useBaseUrl('/img/…') ulanýandygyny we ýerli öň synanyşykda çykýandygyny tassyklaň. Favikonlar

  • Köp‑ölçegli favicon.ico ähli guruluş ýollarynda (Make + skriptler) website/scripts/build-favicon.mjs arkaly awtomatiki döredilýär.

  • El bilen ädim talap edilmeýär; icon-*.png-i täzeläniňiz ýeterlik. Gözden geçiriş maslahaty

  • Terjime edilen dokumentlerde front‑matter id üýtgemezsin; diňe bar bolsa title we sidebar_label-i terjime ediň.

clean

  • Maksat: ýerli build/preview artefaktlaryny aýyrmak.
  • Ulanylyşy: make clean
  • Aýyrýar (bar bolsa):
  • tmp/
  • web-local-preview/
  • website/build/

commit

  • Maksat: format, synag, üýtgeşmeler gündeligini täzeläň, commit we push.
  • Ulanylyşy: make commit
  • Jikme-jik: Prettier (ýazma), make test, make test_i18n işledýär; sahnalaşdyrylan tapawutlar bar bolsa üýtgeşmeler gündeligine goşýar; origin/<branch>-a push edýär.

eslint

  • Maksat: ESLint-i tekiz konfigurasiýa arkaly işlediň.
  • Ulanylyşy: make eslint

help

  • Maksat: ähli nyşanalary bir setirlik düşündiriş bilen sanap görkezmek.
  • Ulanylyşy: make help

lint

  • Maksat: web-ext ulanyp MailExtension-y lint etmek.
  • Ulanylyşy: make lint
  • Bellikler: wagtlaýyn sources/manifest_LOCAL.jsonsources/manifest.json göçürýär; gurlan ZIP-leri äsgermeýär; duýduryşlar piliňi şowsuzlandyrmaýar.

menu

  • Maksat: Make nyşanasyny we islege görä argumentleri saýlamak üçin interaktiw menýu.
  • Ulanylyşy: argumentler bermän make işlediň.
  • Bellikler: eger whiptail elýeterli däl bolsa, menýu make help-a gaýdyp barar.

pack

  • Maksat: ATN we LOCAL ZIP-leri gurmak (lint-e bagly).
  • Ulanylyşy: make pack
  • Maslahat: gaplamazdan öň sources/manifest_*.json ikisinde-de wersiýalary artdyryň.

prettier

  • Maksat: repo-ni ýerinde formatlamak.
  • Ulanylyşy: make prettier

prettier_check

  • Maksat: formatlamany barlamak (ýazma ýok).
  • Ulanylyşy: make prettier_check

prettier_write

  • Maksat: prettier üçin lakam.
  • Ulanylyşy: make prettier_write

test

  • Maksat: Prettier (ýazma), ESLint, soňra Vitest (gurnalanso örtük) işlediň.
  • Ulanylyşy: make test

test_i18n

  • Maksat: goşundy setirleri we websaýt dokumentleri üçin i18n‑ugurly synaglar.
  • Ulanylyşy: make test_i18n
  • Işledýär: npm run test:i18n we npm run -s test:website-i18n.

translate_app / translation_app

  • Maksat: goşundynyň UI setirlerini EN-den beýleki locale-lara terjime etmek.
  • Ulanylyşy: make translation_app OPTS="--locales all|de,fr"
  • Bellikler: açar gurluşyny we ýer tutujylary saklaýar; translation_app.log-e log ýazýar. Skript görnüşi: node scripts/translate_app.js --locales ….

translate_web_docs_batch / translate_web_docs_sync

  • Maksat: websaýt dokumentlerini website/docs/*.md-den website/i18n/<locale>/...-e terjime etmek.
  • Öwülýän: translate_web_docs_batch (OpenAI Batch API)
    • Ulanylyşy (flaglar): make translate_web_docs_batch OPTS="--files <doc1,doc2|all> --locales <lang1,lang2|all>"
    • Miras pozisionally ýagdaý entek kabul edilýär: OPTS="<doc|all> <lang|all>"
  • Hereketi: JSONL gurýar, ýükläp goýýar, her 30 sekuntda barlaýar, netijeleri düşürýär, faýllary ýazýar.
  • Bellik: batch işi dolmak üçin 24 sagada çenli wagt alyp biler (OpenAI-nyň batch penjiresine görä). Konsol her barlagda geçen wagty görkezýär.
  • Gurşaw: OPENAI_API_KEY (hökmany), islege görä OPENAI_MODEL, OPENAI_TEMPERATURE, OPENAI_BATCH_WINDOW (deslapky 24s), BATCH_POLL_INTERVAL_MS.
  • Miras: translate_web_docs_sync
    • Ulanylyşy (flaglar): make translate_web_docs_sync OPTS="--files <doc1,doc2|all> --locales <lang1,lang2|all>"
    • Miras pozisional görnüşi entek kabul edilýär: OPTS="<doc|all> <lang|all>"
  • Hereketi: jübüt-jübüt sinhron islegler (batch birleşdirme ýok).
  • Bellikler: OPTS goýberilende interaktiw soraglar görkezilýär. Iki režimde-de kod bloklary/ goşmaça kod üýtgewsiz saklanýar we front‑matter id üýtgedilmeýär; loglar translation_web_batch.log (batch) ýa-da translation_web_sync.log (sync) içine ýazylýar.

translate_web_index / translation_web_index

  • Maksat: websaýt UI setirlerini (baş sahypa, üst menýu, ast menýu) website/i18n/en/code.json-den website/i18n/<locale>/code.json aşagyndaky ähli locale-lara terjime etmek (en-i hasaba almaýar).
  • Ulanylyşy: make translate_web_index ýa-da make translate_web_index OPTS="--locales de,fr [--force]"
  • Talaplar: OPENAI_API_KEY eksport ediň (islege görä: OPENAI_MODEL=gpt-4o-mini).
  • Hereketi: JSON gurluşyny tassyklap barlaýar, gyrk ýaýly ýer tutujylary saklaýar, URL-leri üýtgetmeýär we barlag ýalňyşlarynda köpçülikleýin düşünjili gaýtadan synanyşyk edýär.

web_build

  • Maksat: dokumentler saýtuny website/build-e gurmak.
  • Ulanylyşy: make web_build OPTS="--locales en|de,en|all" (ýa-da BUILD_LOCALES="en de"-i goýuň)
  • Içki detaylar: node ./node_modules/@docusaurus/core/bin/docusaurus.mjs build [--locale …].
  • Garaşyklar: diňe website/node_modules/@docusaurus ýok bolsa, website/-de npm ci işledýär.

web_build_linkcheck

  • Maksat: oflajn howpsuz baglanyşyk barlagy.
  • Ulanylyşy: make web_build_linkcheck OPTS="--locales en|all"
  • Bellikler: tmp_linkcheck_web_pages-e gurýar; GH Pages baseUrl-i /-e täzeden ýazýar; daşky HTTP(S) baglanyşyklaryny geçýär.

web_build_local_preview

  • Maksat: islege görä synaglar/baglanyşyk barlagy bilen ýerli gh‑pages öň synanyşygy.
  • Ulanylyşy: make web_build_local_preview OPTS="--locales en|all [--no-test] [--no-link-check] [--dry-run] [--no-serve]"
  • Hereketi: ilki Node öň synanyşyk serwerini synap görýär (scripts/preview-server.mjs, /__stop goldaýar), soň python3 -m http.server-a gaýdyp barýar; 8080–8090-da hyzmat edýär; PID web-local-preview/.server.pid-de.

web_push_github

  • Maksat: website/build-i gh-pages şahasyndaky ýerine push etmek.
  • Ulanylyşy: make web_push_github

Maslahat: Makefile tarapyndan ulanylýan paket dolandyryjyny üýtgetmek üçin NPM=…-i goýuň (deslapky npm).