Creating pathNameTable.json

pathNameTable files are used to create alternate folder structures for library packages. They are also needed to translate the folders’ and library parts’ names (Creating fileNames.po and folderNames.po).

For creating and editing pathNameTable files, it is advised to use VSCode with the latest version of the GDL Add-on, which includes a helpful tool for this process.

First, create a new empty JSON file in the library package source’s root folder (or into any of its subfolders). The file’s name should follow the pathNameTable*.json format, where the * means any character (the add-on also shows a warning message for this).

Once you have created the .json file, open the library package’s root folder in VSCode.

Select the .json file in the file list, then switch to the Library Explorer view.

In this view, click “Check content against filesystem” to automatically generate the contents of the pathNameTable.json. A pathNameTable.json file’s contents look similar to the following example:

    {
        "fileName": "pathNameTable.json",
        "meta": {
            "translatePathName": null
        },
        "virtualFileName": "pathNameTable",
        "virtualPath": [
            "Root Folder",
            "Subfolder 1",
            "Subfolder 2"
        ]
    },

fileName – refers to the name of the file in the to-be-built .lcf (.gsm for library parts, .tif instead of .svg), with the file extension

meta – contains additional, optional information. Any tags that you might find useful can be added under this. Neither Archicad nor any other .exe function handles data entered under meta.

translatePathName – it can have three different values: null/true/false. These values are currently only used by Graphisoft’s in-house localization tools. Still, you may use the same methodology, because a public version of this tool that relies on this tag may become available in the future. You can skip editing these tags if you don’t intend to translate folder and file names that is, you want to use the alternate folder structures but in a single language).

  • null: this is the default value that gets assigned at pathNameTable generation. You should decide for each file name whether to use true or false. In the final version of the pathNameTable, none of these values should stay as null.

  • true: files and folders needing translation should be marked with true (generally the placeable library parts).

  • false: files and folders that do not need to be translated should be marked with false (use this value for macros, subtypes, and images).

All filename and foldername strings are added into fileNames.po and folderNames.po regardless of their translatePathName value, however the translation system can automatically skip strings marked with false so they stay the same as the original.

virtualFileName – the untranslated name with which the file appears in Archicad. To avoid confusion, it should be kept the same as the fileName, without the file extension. This name is added to fileNames.po at its creation.

virtualPath – describes the location of the file within the folder structure shown in Archicad. This is the key feature of pathNameTables (besides providing a base for translating file and folder names). Each folder in the path is added to folderNames.po at its creation.

If you want a different folder structure for specific language versions, you have to create multiple pathNameTable files with different virtualPaths. If you want the same structure and only have different translations for the path, you can manage that with a single pathNameTable.json and multiple folderNames.po files.

By default, all paths will be generated relative to the root folder (e.g., any files directly under the root folder will have an empty path shown in the brackets).

You can edit the paths manually or with drag-and-drop. For the visual drag-and-drop version, expand the pathNameTable.json on the left side while still in the Library Explorer view.

Add new subfolders or rename the existing ones (via the buttons on the right that appear when a folder is highlighted), then drag each file to its designated folder. The text-based pathNameTable file will be automatically updated.

After you are done with your changes, click on Check Content Against Filesystem again to remove all unused folders automatically.

Keep in mind

pathNameTables describe the contents of the binary libpack. This is important in the case of MappingDefinitions.json (which is generated from parammapping.xml files during the build process). The Check Content Against Filesystem operation doesn’t add it automatically (because it doesn’t exist in the hsf format), so make sure to add it manually to all pathNameTable.json files!

Whenever you add, remove, or rename ANY files under the library package’s source root folder (except for under a library part’s folder, which will all be turned into a single .gsm), you have to update the pathNameTable(s) as well, otherwise build warnings/errors may come.

If you are working on multiple library packages (or want to expand the official Graphisoft library), ensure that the folder names and structures are the same so that Archicad can merge the folders appropriately.

Adding to the library package

Pair your relevant language versions with their respective pathNameTables.json files in the localizationData.info. See more on this in Libpack info files.