Skip to content

Localizing Marketplace

Jump to bottom
Isaac edited this page Nov 14, 2022 · 13 revisions

If you are interested in making Marketplace more accessible and closer to you and the people using your language, you can take part in translating Marketplace.

Below are the guides and requirements when submitting your translation:

Requirements

To ensure we can validate the quality of the translation, we ask that you meet these criteria before submitting your contribution:

  • You must be fluent in English. (Used for the source strings needed to be translated)
  • You must be fluent in your language of choice. (It is recommended that you are a native speaker of the language of choice, or that you have reached at least an intermediate level of mastery)
    • We will not be accepting raw translation from translating services (eg. Google, Yandex)
  • You should be somewhat familiar with Yarn and/or TypeScript, JSON. (optional & recommended, if you want to test how your strings would look like put into use inside Marketplace.)

After you have ensured that you met the required criteria, follow these guides below to get started:

Getting started

  1. Marketplace uses whichever language that your Spotify client is using. If you want to find out if Spotify supports your language, follow this guide:
  • On your Spotify client interface, click on your profile card on the top-right corner of the client -> click on Settings
  • On the Language section, click on the dropdown to open it and scroll to find your language of choice:

image

If you cannot find the language that you need, it means that Spotify does not support your language and for that reason, Marketplace will not be able to use your translation (for now). Otherwise, if you do find your language supported by Spotify, continue reading the guide below.

  1. If you are unfamiliar with language codes and/or you do not know what is the language code of your chosen language, refer to this table and find the corresponding language code for your chosen language.

  2. After you have figured out the language code that you need, refer to the locales folder in this repository to see if your language has had support.

Translation files' title should follow [your-language-code].json (eg. en.json)

  • If your chosen language is present and you wish to improve it, simply edit the translation file, its strings, and make a Pull Request.
  • If your chosen language is not present and you wish to add support for it, refer to the sections below:

Note: en.json is the source file and should be used as the reference for your translation.

Setting up

If you wish to add support for a new language, you need to set up an environment.

  1. Start by forking this repository and cloning your fork locally. Afterwards you can locate the locale folder inside your clone in /packages/marketplace/src/resources/locales.
  2. Create a file inside the folder titled [language-code].json, replacing [language-code] with your language code of choice.
  3. Copy the content of en.json and place it inside the file.
  4. Translate the strings to your language of choice. Refer to the section below for some notes.

Format

A translation file, in addition to a following the proper format of a JSON file, should follow the following format:

{
  "translations": {
    "section": {
      "key": "translation"
    }
  }
}
Key Explanation
"section" The section in which the translated string is used
"key" The identifier for a string inside each section used in different part of the corresponding section
"translation" The translation string used for each section. Can be either a translation or an expression in case of reusing a string $t([section].[key]).

A full example can be seen in en.json shown below, with some additional notes:

{
  "translation": {
    "settings": {
      "title": "Settings",
      "optionsHeading": "Options",
      "starCountLabel": "Stars count",
      "tagsLabel": "Tags",
      "devToolsLabel": "Theme developer tools",
      "hideInstalledLabel": "Hide installed when browsing",
      "colourShiftLabel": "Shift colours every minute",
      "tabsHeading": "Tabs",
      "resetHeading": "Reset",
      "resetBtn": "$t(settings.resetHeading)", // Strings can be re-used using `$t([section].[key])`
      "resetDescription": "Uninstall all extensions and themes, and reset preferences"
    },
    "tabs": {
      "Extensions": "Extensions",
      "Themes": "Themes",
      "Snippets": "Snippets",
      "Apps": "Apps",
      "Installed": "Installed"
    },
    "snippets": {
      "addTitle": "Add Snippet",
      "editTitle": "Edit Snippet",
      "viewTitle": "View Snippet",
      "customCSS": "Custom CSS",
      "customCSSPlaceholder": "Input your own custom CSS here! You can find them in the installed tab for management.",
      "snippetName": "Snippet Name",
      "snippetNamePlaceholder": "Enter a name for your custom snippet",
      "snippetDesc": "Snippet Description",
      "snippetDescPlaceholder": "Enter a description for your custom snippet",
      "snippetPreview": "Snippet Preview",
      "optional": "Optional",
      "addImage": "Add image",
      "changeImage": "Change image",
      "saveCSS": "Save CSS"
    },
    "reloadModal": {
      "title": "Reload",
      "description": "A page reload is required to complete this operation.",
      "reloadNow": "Reload now",
      "reloadLater": "Reload later"
    },
    "devTools": {
      "title": "Theme Dev Tools",
      "noThemeInstalled": "Error: No marketplace theme installed",
      "noThemeManifest": "Error: No theme manifest found",
      "colorIniEditor": "Color.ini Editor",
      "colorIniEditorPlaceholder": "[your-colour-scheme-name]",
      "invalidCSS": "Invalid CSS"
    },
    "grid": {
      "newUpdate": "New update",
      "addCSS": "Add CSS",
      "search": "Search",
      "installed": "Installed",
      "lastUpdated": "Last updated {{val, datetime}}", // `{{val, datetime}}` are variables and should not be translated
      "externalJS": "external JS",
      "dark": "dark",
      "light": "light"
    },
    "readmePage": {
      "loading": "Loading...",
      "errorLoading": "Error loading README"
    },
    "github": "GitHub",
    "install": "Install",
    "remove": "Remove",
    "save": "Save",
    "colour_one": "colour",
    "colour_other": "colours",
    "favourite": "favourite"
  }
}

Registering your language

After you have finished with your translation file, navigate to packages/marketplace/src/app.tsx to register your language so Marketplace can put it into use.

Import your language file at the top of the file as follows:

import [your-language-code] from "./resources/locales/[your-language-code].json";

and continue to navigate to the language code section inside the file and place your language code inside it:

i18n
  .use(initReactI18next) // passes i18n down to react-i18next
  .use(LanguageDetector)
  .init({
    // the translations
    resources: {
      en,
      "en-US": enUS,
      fr,
      [your-language-code],
    },

If your language file has a region indicator, you must import it without the hyphen and assign the correct language code later on.

eg.

import frCA from "./resources/locales/fr-CA.json";

i18n
  .use(initReactI18next) // passes i18n down to react-i18next
  .use(LanguageDetector)
  .init({
    // the translations
    resources: {
      en,
      "en-US": enUS,
      fr,
      "fr-CA": frCA,
    },

Afterwards, save the file and your translations are ready to be published! You can now commit your changes to your fork and open a Pull Request so that others can start using your work.

If you wish to see how your translations are put into use, refer to the sections below.

Testing your translation

Refer to Development on how to build your own dev instance of Marketplace and try out your changes.

After you have finished building and applying the new instance of Marketplace, simply change your Spotify client's language and see the new changes.

If you can't see Marketplace using your translation, make sure you have registered your language in the aforementioned section, double-check if you are using the correct language code (recommend using a general code, eg. fr, de).

If that still doesn't work, ask your questions in our Discord server (linked in the footer) and we'll answer all your queries.

Contributors

Below are the list of Proofreaders and Translators of the supported language whom have dedicated their work to localizing Marketplace:

  • English:
    • Owned by the Spicetify collaborators.
  • English (United States):
  • French/Français:
  • Spanish:
  • Traditional Chinese/中文:

Wish to become a Proofreader, or if you wish to be credited for your work? Simply mention the repository maintainers (@CharlieS1103, @theRealPadster, and @kyrie25) and we will have you listed as soon as possible.

Join our Discord for discussions.
Clone this wiki locally