Skip to main content

Rigi Documentation

Define a project

The empty project created as part of the solution has quite an overwhelming layout.

Define1.png

The screenshots show the Source Files directly under the project. The latest version of the Solution Editor shows two nodes: Parser Settings and Source Files.

Define2.png

  1. Enter project settings:

    • Name: Enter a project name. This name is only used for display purposes. The entered project name is shown in the tree view.

      Define3.png

    • Project: This is the location of the project file (.rigproj). The absolute path is shown in the UI, but under the hood, Rigi stores relative paths to the location of the solution file (.rigsln).

    • Root path: This is the root folder containing the files that must be localized. The initial value is the location of the project file. The tree view shows the files that are located in that path.

      Define4.png

      In this example, the source files for this particular project are not located in piwik\project but in folder piwik\files.

      Define5.png

      • Click the Browse button to select that folder. The tree view now shows the subfolders and files in that folder. The root path has a relative location to the solution.

        Define6.png

    • ID: It is recommended to define a project ID for this project. Rigi concatenates three identifiers (separated with a dot) to determine a unique ID within the solution:

      • Project ID – the identifier that is described here.

      • File ID – each file in a project will be assigned a unique File ID.

      • String ID – each file contains localizable strings. Each string has a unique ID.

        If the solution only contains one project, you could leave it empty. If a solution contains multiple projects, there is a risk of collisions if files in both projects have the same File ID and String ID.

    • Read-only: Define if the strings in a project are read-only (default = no). Rigi provides a WYSIWYG translation environment for translators and reviewers. Rigi substitutes translations in the Rigi screenshot with the actual translation.

      Some software projects can have different teams working on various projects with different localization cycles. In those cases, it is possible to import the translations from existing projects as a reference for the translator. This means that translators can see the translations but not change them.

  2. Select Solution > Save.

  3. Enter target rules.

    A Rigi project contains source files with translatable texts. The objective of Rigi is to generate localized target files that contain the translations. The location and name of those files are project-dependent.

    Localized Java properties files, for example, are usually located in the same folder as the source file and have the locale as an extension. For example, the German target of string.properties gets the name strings.de.properties. In the Piwik sample project, the JSON files have the name <locale>.json. The source is en.json, and the target (German) is de.json. This requires that each resource file be located in a separate folder.

    Define7.png

    Each target rule has a unique ID. The rule itself contains variables $(xyz) that represent, for example, the locale, source path, and file extension.

    It is recommended to add at least one source file to the project (see Step 4 below). This is required to test the resolved path of the target rule and see the variables.

    1. Click Add. This dialog consists of three parts:

      Define8.png

      • Data entry, in which you enter the ID and the Rule.

      • Test target rule, in which you select the source file ID, Parser, and Target language to see the resolved path.

      • Variables: an overview of variables. The table shows the variable name and its value (derived from the selected source file).

    2. Enter the ID, for example, TR.

    3. Enter the rule.

      Double-click a variable in the Variables field to insert it in the Rule field.

      Please note that the Variable table supports quickly capturing the required target rule and ensures that all characters are written properly in the path. Try to take as much advantage of the variables as possible when creating your target rule.

      The Resolved path field presents the name and location of the target file with the current rule. It acts as a check functionality when (old) target files are available in the target folder. Resolved path checks if there is an existing file at the path given in the Rule. As an additional aid, the text is colored red if the target file does not exist; otherwise, it is green.

      In the example below, the German target file for en.json is located in the same folder ($(sourceFilePath)) as the source file and will get the name ($(targetLocale)$(sourceFileExt)). This rule is then resolved to lang\de.json. That file already exists, and therefore, it is colored green.

      Define9.png

      This way, you can configure any mapping.

      The project files implement a variable mapping mechanism. For example, $(targetLocale) maps to de. It can be overridden to map to any other value (e.g., Berlin). That mapping is not supported by the user interface of the Solution Editor but can be achieved by editing the project file in an editor.

    4. Click OK.

      It is possible to override the values of variables for specific locales. For example, $(sourceFileExt) can be overridden with .ItalianJson if the locale is it-IT. For details, see the Advanced editing section > Mapping of variables in target rules.

  4. Add the source file.

    A project consists of files. The source file is located in a folder and has a filename.

    Each file needs to be assigned with the following attributes:

    • File ID. This is a unique identifier for this file within this project.

    • Parser. Select the Rigi parser that must be used for this file. Rigi comes with several parsers. It is possible to implement your own parsers using the Rigi Parser SDK.

    • Target rule.

    All source files in the Piwik demo application have the same name: en.json. The following steps explain how to add one source file at a time.

    1. In the tree view, select the file that must be added.

    2. Right-click to see the context menu.

    3. Select Include in Project.

      Define10.png

      The file is added to the source files overview. The File ID gets a unique name (the name of the file plus an optional number), a default Parser is assigned (based on the extension), and a target rule.

      Define11.png

    4. (Optional) You can change the File ID. File IDs are usually short names. Make sure that each File ID is unique within a project.

    5. Make sure that the correct Parser and Target rule are selected.

      Under the hood, the file is added to the .rigproj file:

      Define12.png

      You can add other files by repeating the previous steps or using the mass-adding option. For details, see the Mass add source files guide.

  5. Enter parser settings.

    Use parser settings to configure the parser.

    The resx parser, for example, recognizes {0}, {1}, ... as placeholders for variables. It is possible to define additional placeholder patterns for any parser. For example, define the regular expression %.+?% to recognize variables such as %var%. You can define as many additional placeholders as you like (one per line).

    Define13.png

    Hover the mouse over the setting to get an additional explanation.

    • The JSON parser does not have additional settings besides the Additional Placeholders.

    • The Properties parser has quite some settings. In the example below, an additional placeholder is defined to recognize a pattern such as {samplevar} as a variable.

      Define14.png

  6. (Optional) Delete a source file.

    Engineers make changes to projects. It can happen that they removed or renamed a source file. In that case, the file is marked.

    For example, we defined a reference to the fake.json file in the Piwik .rigproj file. Project files not existing on disk are marked in the Solution Editor.

    Define15.png

    To remove that file from the project, perform the following steps:

    1. In the tree view, select the file that must be removed.

    2. Right-click to see the context menu.

      Define16.png

    3. Select Exclude from project.

      The file is removed from the source files overview.

    You can remove all unused files from a project at once. Use the context menu at project level.

    Define17.png