Skip to content
Tutorials Center
My learning

Topics

Lesson 7 of 36 · Manifest V3 and Structure

Folder Structure, Icons and Translations

Organize an extension project, create correctly sized icons including SVG-to-PNG, and translate your extension with _locales, messages.json and chrome.i18n.

An extension can start as three files, but real ones grow. A tidy folder keeps your manifest readable, makes reloading predictable and helps when you later add TypeScript, a bundler or tests. This lesson covers folder layout, icons and internationalization (i18n).

A layout that scales

TEXT
my-extension/
  manifest.json
  src/
    background/
      service-worker.js
    content/
      content.js
      content.css
    popup/
      popup.html
      popup.js
      popup.css
    options/
      options.html
      options.js
  icons/
    icon-16.png
    icon-32.png
    icon-48.png
    icon-128.png
  _locales/
    en/messages.json
    es/messages.json

Rules that apply no matter how you organize:

  • Every path in the manifest is relative to the folder holding manifest.json.
  • Chrome ignores files you do not reference, but it packages the whole folder, so keep notes, screenshots and node_modules out of the folder you publish.
  • File and folder names beginning with an underscore are reserved by Chrome (_locales, _metadata). Do not invent your own.
  • Keep one HTML file per extension page and give scripts their own files (no inline code).

If you use a bundler, your source folder and your dist folder differ; you load dist/ in Chrome. A common pattern copies manifest.json and icons into dist/ during the build.

Icons

Chrome shows your icon in several places, each wanting a different size:

Size Where it is used
16 px Extensions page favicon, context-menu entries
32 px Windows toolbar scale
48 px Extensions management page
128 px Install dialog and the Chrome Web Store
JSON
"icons": {
  "16": "icons/icon-16.png",
  "32": "icons/icon-32.png",
  "48": "icons/icon-48.png",
  "128": "icons/icon-128.png"
},
"action": {
  "default_icon": {
    "16": "icons/icon-16.png",
    "32": "icons/icon-32.png"
  }
}

Use PNG. The toolbar and store accept PNG reliably, and SVG is not supported for the manifest's icon keys. Design on a 128-pixel canvas, leave a small transparent margin, and test how the 16 px version looks: fine detail disappears, so use a bold simple shape.

If you design an icon as an SVG, you can export the four PNG sizes from it. The stand-in below draws a simple SVG onto a canvas at four sizes so you can see how it scales down, the same way an export script would.

One drawing, four sizes

In the real toolbar you can also change the icon at runtime with chrome.action.setIcon(), which accepts ImageData drawn on an OffscreenCanvas (the service worker has no DOM, but it has OffscreenCanvas).

Translating your extension (i18n)

Chrome has built-in i18n. You write messages once per language, and Chrome picks the one matching the user's browser language, falling back to the default.

  1. Add "default_locale": "en" to the manifest.
  2. Create _locales/<code>/messages.json for each language.
  3. Reference messages as __MSG_name__ in the manifest and CSS, or call chrome.i18n.getMessage("name") in JavaScript.
JSON
{
  "manifest_version": 3,
  "name": "__MSG_extName__",
  "description": "__MSG_extDescription__",
  "version": "1.0.0",
  "default_locale": "en"
}

_locales/en/messages.json:

JSON
{
  "extName": { "message": "Tab Counter" },
  "extDescription": { "message": "Shows how many tabs you have open." },
  "tabsOpen": {
    "message": "You have $COUNT$ tabs open",
    "placeholders": { "count": { "content": "$1", "example": "7" } }
  }
}

_locales/es/messages.json has the same keys with Spanish text. In code:

JavaScript
const text = chrome.i18n.getMessage("tabsOpen", ["7"]);

Language codes use underscores for regional variants: pt_BR, en_GB.

A stand-in for chrome.i18n

This reproduces the lookup rule: use the user's language if it exists, otherwise the default, and substitute placeholders.

JS getMessage, simulated

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Check your understanding

Quick check · 3 questions

of 3 answered You scored / 3 · perfect!

  1. 1. What is the paths rule inside manifest.json?

    Every file reference in the manifest is resolved against the extension root, the folder that holds manifest.json.
  2. 2. Which icon format should you use for the manifest icons?

    Provide PNGs in 16, 32, 48 and 128 pixel sizes; SVG is not supported for manifest icons.
  3. 3. What does default_locale do?

    It is the fallback language and is required whenever a _locales folder exists.

Summary

  • Keep manifest-relative paths and one file per page/script.
  • Underscore-prefixed folders like _locales are reserved.
  • Supply PNG icons at 16, 32, 48 and 128 px and test the small one.
  • Use _locales/<lang>/messages.json, __MSG_x__ and chrome.i18n.getMessage.
  • Always set default_locale when translating.

Next: Match Patterns: Choosing Where to Run