Description

Changelog

Reviews (0)

Set and See Localization Key

Acknowledgments

Thanks to Banana Holograma for their script to read CSV files from the Godot Essentials repository, specifically from the file_manager.gd file.

Description

TIP

To properly view the documentation, I recommend checking it in the repository.

This is a plugin developed for Godot. It works with version 4.5 and later.
This plugin is related to the localization phase for multiple languages in a Godot project, using CSV files and specifically their reference keys.

What are CSV files?

CSV files are a type of file frequently used for video game translations. They consist of a table where the first column contains the reference keys, and the other columns correspond to each language. They are known as spreadsheets. They are commonly created in office suites such as LibreOffice. When saving the file, make sure to save it with the ".csv" extension and in "UTF-8" format.

More info in the Godot documentation: Localization using spreadsheets
By default, in Godot, if a reference key is placed in a Label, the game will access and set the value for the corresponding language when it starts. Currently, there is no functionality in the editor to place these keys. This plugin addresses that need.
It allows for faster placement of language keys from CSV files in nodes with the "Text" property, as well as in user-created variables within scripts. When the plugin is activated, two buttons, "Set" and "See," will appear. Clicking these buttons will open windows for selecting and viewing the keys.
In the "See" window, you can consult the key entered in the inspector. The value of the corresponding language would be displayed, as well as the option to consult it in the other languages of the project.
In the "Set" window, all the keys will be listed, grouped by their corresponding 'csv' file. Each group of keys can be minimized/maximized by clicking on the arrow next to the group name.
- By clicking once on a key, the value of the selected language will be displayed (it can also be consulted in other languages).
- If pressed twice, it will place the reference key in the corresponding variable/field.
- A key finder is also available, where it will filter and group similarities in the top 'Treekey'. For all the keys to appear again, it would be enough to leave the field empty.

Installation

Add the 'set_and_see_localization_key_plugin' directory to the "addons" folder. e.g:
- res://addons/set_and_see_localization_key_plugin
Activate the plugin:
- Project > Project Settings > Plugins > Activate **Set&See Localization Keys in the inspector**
Specify the ".csv" file folder. (See Configuration)
Update references. (See Configuration)

Configuration

Create a folder to store all the ".csv" files. Importing them will generate "Translation" files that must be manually added in:
- Project > Project Settings > Localization > Translations > "Add..." button
NOTE

Generating "Translation" files is not part of the plugin; it's a system natively included in Godot. It's necessary to access language keys during gameplay, as well as for some parts of the plugin.

TIP

It's advisable to distribute the keys across several "csv" files for better visualization in the "TreeKey" of keys, as it groups them by the containing "csv" files.
Go to the plugin settings:

Project > Project Settings > General > Internationalization > Set And See Keys
- Path Localization Directory. The plugin needs a folder to store all the "csv" files to read and load the reference keys. It also reads subfolders.
  
  IMPORTANT
  
  When the directory is changed, you must click the Reload CSV files button to update the reference.
  
  NOTE
  
  If this property does not appear, simply activate the 'Advanced Settings' CheckButton.
- Name Extension is used to activate the functionality in scripts, for one of the two Scripts modes (See Functionality). If a variable has the @export annotation, is of type String or StringName, and ends with that extension, the Set&See option will be activated in the inspector. e.g:
  
  IMPORTANT
  
  The extension can be modified at any time, but it is important to note that variables written with the old extension will stop working in this mode and must be changed. Therefore, do this at the beginning of the plugin installation.
- Reload CSV files is a button that will update the references to CSV files if they are edited in parallel by an external application, or if the folder directory is changed.
  
  NOTE
  
  References will also be updated if the project is restarted.

Functionality

There are three modes; integrated into Nodes, integrated into Scripts, and as a Node to be added in the Editor (since version 1.2).
- Nodes (embedeed): The Nodes with the Text property will have the two Set and See buttons directly above the property. It also works with LineEdit in its PlaceHolder, as well as in the Label3D, among others.
- Scripts (embedeed): There are two ways: using the Name Extension or the @export_category annotation.
  - Name Extension: By writing that extension at the end of the variable name in the script. It must also include the @export annotation and be of type String or StringName. e.g:
  - @export_category, writing this annotation with the argument: VerbumInser.NAME_CATEGORY
    - The two buttons will appear, where you can select the script variable(s) that are of type String or StringName, and with the @export annotation.
      
      IMPORTANT
      
      There must be at least one variable with the @export annotation and (preferably) of type String/StringName, for the two buttons to appear.
      
      TIP
      
      I recommend placing it at the top, or below all the @export statements in the script for visual reasons.
      
      NOTE The @export_category mode would be incompatible with Name Extension mode variables.
    - In this mode, you can select a variable from the inspector in the "Set" and "See" windows.
  NOTE
  
  Both (Name Extension Mode and Export Category Mode) serve the same purpose. Choose the one that best suits your needs.
  
  Why use reference keys in scripts?
  
  This can be useful for creating object and character cards, dialogue references, etc.
  
  How would they be used in code?
  
  There are two ways: with the tr() or TranslationServer.translate() methods, using the reference key as an argument. I recommend reading the Godot documentation.
IMPORTANT

The scene must be saved to apply the changes to the variables.
- 'SetAndSeeButtonEditor' Node (since version 1.2): It is a version of the 'Button' Node, but with the name 'SetAndSeeButtonEditor'. It's designed to be added to embedded/floating plugins in the Editor, especially those of the 'Graph-based' type, although it would also work with any other plugin integrated into the Editor.
  - The button has two properties: Mode and Target Text Node.
    - Mode: These are the classic 'Set' and 'See'. When the button is pressed, it activates the corresponding window.
    - Target Text Node: This must be a node with the Text property, to which the effect of the selected mode is applied.

Extra

Since version 1.2: The language value field in the 'Set' and 'See' windows now supports the 'BBCode' format.

Uninstallation

FIRST IMPORTANT: Project > Project Settings > Plugins > Disable "Set & See Localization Keys in the inspector". Then you can delete the plugin folder.