Adding a New Project¶

The following page describes how to make your projects localizable with your Pontoon instance.

Pontoon specializes in using version control systems as the source and store of localizable strings. While internal Pontoon DB can be used for that purpose as well, steps below assume you store strings in a GitHub repository.

Verify that the project is properly localizable¶

Before you can set up a new project in Pontoon:

1. Ensure your project works with one of the supported l10n frameworks:

   • .dtd
   • .ftl (Fluent)
   • .ini
   • .json (WebExtensions)
   • .json (key-value)
   • .po (Gettext)
   • .properties
   • .xliff
   • .xml (Android)

2. Extract localizable strings into resource files.

3. Push resource files to your GitHub repository.

4. Make sure your Pontoon instance has write access to your repository (see this document).

It’s important to also check the files for localization issues before exposing them to localizers: unclear strings, lack of localization comments, missing plural forms are some of the things to check.

Folder structure¶

To let Pontoon discover your localizable files, you'll either need to specify paths in the project configuration file or strictly follow the file and folder structure as expected by Pontoon:

1. Locale folders (including source locale) must be located at the same nesting level of the directory tree. You may want to put all locale folders under a locales folder.
2. Source locale needs to be called templates, en-US, en-us or en. If multiple folders with such name exist in the repository and contain files in a supported file format, the first one will be used.
3. Locale folder names must always match locale identifiers used by Pontoon. If your application requires different identifiers, you can try creating symbolic links to locale folders.
4. Locale code must not be part of the file name.

Correct pattern:

locales/{locale_code}/path/to/file.extension

Incorrect pattern:

locales/{locale_code}/path/to/file.{locale_code}.extension

Create the project¶

Access Pontoon’s admin console and click ADD NEW PROJECT.

The new project will appear in the public list of Projects only after the next sync cycle.

• Name: name of the repository (it will be displayed in Pontoon’s project selector).
• Slug: used in URLs, will be generated automatically based on the repository’s name.
• Locales:
  • Select "Read list of locales from repository" to have Pontoon detect the supported locales from your repository.
    • If a configuration file is provided, you will need to add the locale to its locales list. Resource availability will also be determined by the configuration file.
    • Without a configuration file, you will need to manually add a directory for the locale in the repository in order for the locale to be available in Pontoon. You will then have the option to have all resources added automatically for each locale (default), or only expose in Pontoon resources already present in the repository within the locale directory. The latter means that, for example, bootstrapping a new locale requires manually creating a directory and all necessary files within it.
  • To manually control locales, leave the option to read locales from repository unchecked, then:
    • Select at least one locale. To make things faster it’s possible to copy supported locales from an existing project.
    • The Read-only column can be used to add languages in read-only mode. In this way, their translations will be available to other languages in the LOCALES tab when translating, but it won’t be possible to change or submit translations directly in Pontoon.
    • You can uncheck the Locales can opt in checkbox to prevent localizers from requesting this specific project.
    • The configuration file only determines which resources will be available in Pontoon for each locale. The locales list within the file doesn't have any effect in Pontoon.
    • Without a configuration file, all resources will be automatically available in each locale.
• Repositories: select the type of repository and URL. Make sure to use SSH to allow write access. For example, if the repository is https://github.com/meandavejustice/min-vid, the URL should be git@github.com:meandavejustice/min-vid.git. On GitHub, this is available via the green <> Code button on the repository page, under the SSH tab of the dialog.
• Leave the Branch field empty, unless developers asked to commit translations in a specific branch instead of the default one (usually main or master).
• Public Repository Website: displayed on dashboards. E.g. https://github.com/meandavejustice/min-vid. Pontoon will try to prefill it after you enter Repository URL.
• Configuration file: A path to an optional project configuration file, relative to the source string repository.
• Project info: provide some information about the project to help localizers with context or testing instructions. HTML is supported, so you can add external links. For example:

Localization for the <a href="https://testpilot.firefox.com/experiments/min-vid">Min Vid add-on</a>.

• Internal admin notes: use them e.g. for developer contacts and information that other PMs will find useful when covering for you.
• Deadline: if available, enter project deadline in the YYYY-MM-DD format.
• Priority: select priority level from one of the 5 levels available (Lowest, Low, Normal, High, Highest).
• Contact: select the L10n driver in charge of the project, probably yourself.
• External Resources: provide links to external resources like l10n preview environment. You need to enter the name and the URL for each resource. You can also pick one of the predefined names: Development site, Production site, Development build, Production build, Screenshots, Language pack.

• Visibility: determines who can access the project. Pontoon supports the following visibility types:

• private (default) - only administrators can access the project.

• public - the project is visible for everyone.

• Pretranslation: see the document dedicated to pretranslation.

Click SAVE PROJECT at the bottom of the page, then click SYNC to run a test sync. In the Sync log you should be able to see if it succeeded or failed. If all went well, the new project will appear in the public list of Projects.

IMPORTANT

• The repository must include at least one file for one of the locales. If necessary, you will need to manually create it (it can be empty).
• Once you verify the project works as expected, enable it for the general audience by setting Visibility to Public.

Tags¶

Tags can be used in a project to logically group resources, assigning them a priority. To enable tags for a project, check Tags enabled and save the project.

For each tag, it’s possible to define:

• Name: it will be displayed in project (e.g. /projects/firefox/tags/) and localization dashboards (e.g. /it/firefox/tags/), but also in search filters.
• Slug: used in URLs for tag dashboards, e.g. /projects/firefox/tags/devtools/.
• Priority: like for a project, it’s possible to select a priority level from one of the 5 levels available (Lowest, Low, Normal, High, Highest).

Once you’ve created a new tag, you need to save the project in order to be able to manage the resources associated to the tag itself, using the button highlighted in green.

Resource deadline¶

Like for a project, it’s possible to set a deadline for a Resource.

Go to the resource section of the admin panel, then type the name of your project (e.g. engagement) and hit Enter. All the resources for your project should appear. Click on the one you want to edit, set the deadline in the Deadline field, then click SAVE.