Virtual Folders¶

New in version 2.7.

Virtual folders provide a way to group translations based on any criteria, including a file across all the languages in a project, or files on specific locations. Virtual folders have priority, so they can be used to allow translators to focus on the most important work.

Virtual folders’ attributes¶

Virtual folders have several attributes:

A mandatory lowercase name,
A mandatory location,
An optional priority,
An optional publicness flag,
An optional description,
A field accepting several optional filtering rules.

The location indicates the root place where the virtual folder applies. It can use placeholders for language ({LANG}) and project ({PROJ}).

Note

The / location is not valid and must be replaced by /{LANG}/{PROJ}/. The locations starting with /projects/ are also not valid and must be changed so they instead start with /{LANG}/.

Each virtual folder must have a unique combination of name and location. This means that there can exist two different virtual folders with the same name if they have different locations.

The priority defaults to 1 and accepts any value greater than 0, including numbers with decimals, like 0.75. Higher numbers means higher priority.

By default virtual folders are public. If they are not public then they won’t be displayed, but they are still used for sorting.

Also the virtual folders can have a description which might be useful to explain the contents of the folder or provide additional instructions. This might be handy when using the virtual folders as goals.

The filtering rules specify which translation units are included within a virtual folder. Currently the only supported filtering rule consists of a list of file or directory paths relative to the virtual folder location. Note that it is required to set some filtering rule.

Adding and updating virtual folders¶

To add or modify the properties of virtual folders use the add_vfolders management command.

This command imports a JSON file holding a list of virtual folders, and the files included on each virtual folder along with all their attributes. Check the specs for the JSON format in order to know how to craft a JSON file that fits your needs.

Virtual folders stats¶

Translation stats of virtual folders are automatically calculated.

Translating virtual folders¶

If a virtual folder applies in the current location, then clicking on the links on the overview page will provide the units in priority order when translating in the editor. The priority sorting on the translation editor is calculated taking into account all the applicable virtual folders in the current location, including the not public ones.

Format for the JSON file¶

The JSON file used to import virtual folders consists of a list of virtual folder definitions with the same fields as the virtual folders, except for two differences:

If the description includes newlines those must be escaped.

The following example depicts a basic JSON file:

[
    {
        "name": "user1",
        "location": "/{LANG}/firefox/browser/",
        "priority": 999.99,
        "is_public": true,
        "description": "Most visible strings for the user.",
        "filters": {
            "files": [
                "branding/official/brand.dtd.po",
                "chrome/browser/aboutDialog.dtd.po"
            ]
        }
    },
    {
        "name": "user2",
        "location": "/gl/firefox/",
        "priority": 7.5,
        "is_public": false,
        "filters": {
            "files": [
                "browser/chrome/browser/aboutSessionRestore.dtd.po",
                "browser/chrome/browser/downloads/downloads.dtd.po"
            ]
        }
    },
    {
        "name": "user3",
        "location": "/ru/{PROJ}/",
        "priority": 0.3,
        "filters": {
            "files": [
                "browser/chrome/browser/engineManager.dtd.po"
            ]
        }
    },
    {
        "name": "directories-for-lang",
        "location": "/{LANG}/",
        "filters": {
            "files": [
                "firefox/browser/profile/",
                "firefox/browser/chrome/browser/"
            ]
        }
    },
    {
        "name": "directories-and-files-for-tp",
        "location": "/{LANG}/firefox/",
        "filters": {
            "files": [
                "browser/updater/",
                "browser/chrome/browser/devtools/appcacheutils.properties.po",
                "browser/chrome/browser/migration/"
            ]
        }
    },
    {
        "name": "default",
        "location": "/{LANG}/{PROJ}",
        "description": "All files in all projects for all languages.",
        "filters": {
            "files": [
                "/"
            ]
        }
    },
    {
        "name": "other",
        "location": "/af/firefox/",
        "is_public": true,
        "filters": {
            "files": [
                "browser/chrome/browser/aboutCertError.dtd.po"
            ]
        }
    },
    {
        "name": "developer",
        "location": "/af/firefox/",
        "priority": 0.9,
        "description": "As you can see this\\n description spans\\n several lines.",
        "filters": {
            "files": [
                "browser/chrome/browser/devtools/appcacheutils.properties.po",
                "browser/chrome/browser/devtools/debugger.dtd.po"
            ]
        }
    },
    {
        "name": "install",
        "location": "/ru/{PROJ}/",
        "priority": 5,
        "is_public": true,
        "description": "Installation related strings.",
        "filters": {
            "files": [
                "browser/chrome/browser/migration/migration.dtd.po",
                "browser/chrome/browser/migration/migration.properties.po"
            ]
        }
    }
]