Example: Adding an Icon to phpc

1. Add the SVG file

icons/phpc/frontend-favicons/dashboard/favicon_qa.svg

2. Add the entry to mapping.json

Same plain key/value convention as every library except glyphicons-v1 (see Normalize mapping.json):

{
  // ...existing entries
  "dashboard-qa": "favicon_qa.svg"
}

3. Regenerate mapping-with-filepath.json

phpc loads its icon data from one combined file across all 46 sub-folders, not the individual mapping.jsons:

cd icons/
python ../script/generate-mapping.py ./phpc
mv mapping-with-filepath.json phpc/

Confirm the new key landed in icons/phpc/mapping-with-filepath.json:

"phpc/frontend-favicons/dashboard dashboard-qa": "phpc/frontend-favicons/dashboard/favicon_qa.svg"

4. (Recommended) Regenerate the master mapping

Not read by the app, but this is the repo’s only duplicate-key check across every library — cheap insurance:

cd icons/
python ../script/generate-master-mapping.py .

5. Regenerate keywords.json

Unlike glyphicons-v2, phpc’s 46 mapping.json files are discovered automatically by script/generate-keywords.py (glob.glob("icons/phpc/**/mapping.json")) — the new entry from step 2 is picked up with no edit to the script itself:

python3 script/generate-keywords.py

Trace of what it just did for dashboard-qa (see Keywords & Translations for the full algorithm):

1. Split: "dashboard-qa" → ["dashboard", "qa"]
2. Translate: dashboard → "tableau de bord" (already in translations-en-fr.json), qa → not found, falls back to "qa" unchanged
3. FR phrase "tableau de bord qa" differs from EN "dashboard qa" → added as a keyword
4. More than one word → no-separator join "dashboardqa" also added

"dashboard-qa": ["tableau de bord qa", "dashboardqa"]

This step also rewrites the combined icons/phpc/keywords-with-filepath.json (all 46 keywords.json files merged into one, keyed the same way as mapping-with-filepath.json) — that’s the file IconDropdown.tsx actually imports:

"phpc/frontend-favicons/dashboard dashboard-qa": ["tableau de bord qa", "dashboardqa"]

6. (Optional) Add a synonym via keyword-overrides.json

"qa" isn’t very discoverable on its own — someone searching “test” or “staging” for a QA environment icon would find nothing. This is exactly the case keyword-overrides.json exists for (see When word-by-word translation isn’t enough): qa isn’t a mistranslation, it needs product-knowledge synonyms that have no linguistic link to the word itself.

{
  // ...existing entries
  "phpc/frontend-favicons/dashboard dashboard-qa": ["test", "staging", "recette"]
}

Re-run the same command as step 5 — the overrides get merged in and de-duplicated:

"dashboard-qa": ["tableau de bord qa", "dashboardqa", "test", "staging", "recette"]

7. IconDropdown.tsx — no change needed

phpc is the one library where this is true for any sub-folder, new or existing: iconsPHPC and iconsPHPCKeywords already import the two combined files, and every phpc/** sub-folder is picked up automatically. See Adding a whole new icon set — this is the one case that needs zero code changes even for a brand-new folder.

8. Verify

Run the app, open IconDropdown, and confirm the icon is findable by:

• dashboard-qa (English classname)
• tableau de bord qa (French translation)
• dashboardqa (no-separator English)
• staging (manual synonym, if step 6 was done)