String Editor

The Strings Editor lets you view and edit String files for Petroglyph's games.

Download

To run, just unzip the archive to a location of your choice and start StringEditor.exe.

Thanks to Fynbos from Ultimate Empire at War for suggestions and beta-testing.

Manual
  1. Introduction
  2. Versioned DAT Files
  3. Name versus Index files
  4. The interface
  5. Using the editor
  6. Invalid names
  7. Importing DAT files
  8. Exporting DAT files
  9. The console version
  10. Tutorial

1. Introduction

The Empire at War String Editor came to be because of a demand for a more powerful editor than Dante's relatively simple DAT editor.

The String Editor is more than just an editor for Empire at War's DAT files. It's main features are:

  • Versioning. All changes you have made to the document are remembered, allowing you to check what a string looked like several versions ago.
  • Multiple languages. The editor maintains the values for all strings for all languages in a single document with easy access and comparison. This will benefit translators and prevent cluttering of the disk.
  • Powerful copy, paste, import and export. You can copy and paste strings, even into and from applications such as Excel. Pasting and importing have set manipulation options such as union, difference and intersection allowing you to quickly and easily compare different .DAT files or clipboard fragments.

The String Editor is not meant for people simply looking to change one or two strings in existing DAT files, although that is possible. The String Editor is meant for big mods that have the need for powerful string comparison, translation and management.

2. Versioned DAT files

The editor works on files called Versioned DAT Files (VDF). This is an custom, extended DAT format, which includes the extended options of the editor such as versioning and multiple languages. Conceptually, you should think of these files as follows:

  • A VDF file contains one or more versions.
  • Each version contains one or more strings in one or more languages.
  • Each string contains a name field, a comment field and one value field for each language in the version.

It is important to realize that no matter what language is currently shown in the UI (see next section), the number of strings and their names and comments are the same across all languages.

3. Name versus Index files

When you start a new VDF document, the editor will ask if you want to create a Name-indexed or Index-indexed document. The difference, while subtle, is not trivial.

Consider all strings in the current version as <name, valueen, valuede, ..., comment> rows in a big table, just like shown in the editor. In what order does one store those rows in the file? Any order? Alphabetically? User-determined? Well, depends on what you want to use the exported DAT file for.

Name-Indexed

In one case you want to access strings by name (i.e., you want the string named "LANGUAGE_ENGLISH" and don't care where exactly it is in the file). If this is the case, you'll want to work with a Name-Indexed document. The strings will be sorted before storing to optimize for this kind of search. Empire at War's MasterTextFile_LANGUAGE.dat files are an example of such files.

Index-Indexed

If, however, you want to iterator over all stored strings in some predetermined order, then the strings cannot be sorted before storing as this would break the predetermined order. To indicate this to the editor, you need to create a Index-Indexed document. The strings will be stored in the exported DAT file in exactly the same order as they are shown in the list. Empire at War's CreditsText_LANGUAGE.dat files are an example of such files.

Summary of differences

To summarize, here are the major differences between both document types:

NameIndex
Duplicate namesDisallowedAllowed
PositioningImplicitExplicit
Exported stringsSorted on nameUnsorted
Name-based lookupPossibleNot possible
Index-based lookupPossible, but
not recommended
Possible

4. The interface

UI Screenshot

Above you can see an example of the editor's UI with an opened file.

  • The language drop-down box in the top-right corner allows you to select a language to view. As explained above, changing the language will only change the values, not the names and comments.
  • The version drop-down box next to it allows you to select a version to view.
  • The main list shows all strings in the currently selected version. The columns display, respectively, the string's name, (current language) value, comment and last modified date.
  • The properties group at the bottom of the window displays the name, value and comment for the currently selected string. This is where you edit the strings.
  • The history list shows all changes to this string from the moment of its creation. Select a version in here to see the string's properties in that version.

All versions other than the last one are read-only.

5. Using the editor

Screenshot

To start, you either create a new VDF document or open an existing one via the File menu or the toolbar at the top. The new dialog (shown to the right) will ask you for the initial language of the document as well as the type of the document.

Adding strings

After choosing the appropriate values and accepting, you will be presented with an empty list, save for the single entry that reads "(New string here...)". Select it and fill out the values in the properties window below and notice how the string is immediately inserted in the list. This way you can create as many strings as you'd like.

Languages

Screenshot

To add another language, go to the "Language" menu and select "Add Language". A dialog will ask you to select a language to add. The added language automatically becomes the active language and the values in the list will be cleared.

You can switch to another language by selecting the language in the drop-down box in the upper-right corner of the window, or by using the "Previous Language" and "Next Language" commands in the "Language" menu.

To change (effectively rename) the active language, use the "Change language" command in the "Language" menu.

To delete the active language, and all of its values, use "Delete language" in the "Language" menu.

Editing strings

Screenshot

In the "Edit" menu are, besides the usual commands of "Copy", "Cut", "Paste", "Delete", "Select All", "Find" and "Find Next", also several other commands:

  • Insert String - If the document type is Name-Indexed, this will simply select the "(New String Here...)" item. If the document type is Index-Indexed, this command will insert a new string before the currently selected string in the list.
    In both cases, it will automatically focus the Name field in the properties window so you can start typing immediately.
  • Paste Special - Pastes using one of the available set operators. For more information, see the section "Importing and exporting DAT files". These commands are only available for Name-Indexed documents.
  • Find Next Invalid - Selects the next string below the currently selected string that is marked as "Invalid". To know what constitutes an invalid string, see the next section.
  • Move Strings Up & Move Strings Down - Swaps the selected strings with the strings above or below them, respectively. These commands are only available for Index-Indexed documents.
  • Move Values Up & Move Values Down - Swaps the values of the selected strings with the values of the strings above or below them, respectively. These commands are only available for Index-Indexed documents.

Finding strings

Screenshot

When using the "Find" command in the "Edit" menu, the Find dialog will show up. Here you can enter the search term, whether to perform a case-insensitive or case-sensitive search, whether to match whole words only, which columns to look in, and which strings to consider for the search.

The Find and Find All buttons differ in that the Find button simply finds the next matching string and selects and focus that one. The Find All button selects all matching strings at once, which can then be copied, deleted, etc.

The "Find Next" command in the "Edit" menu simply repeats the last Find operation. Note that for some Find operations, this won't actually change the results.

6. Invalid names

In the "Edit" menu is the "Find Next Invalid" command. This will select the first string below the currently focused string whose name is invalid. But what is an invalid name, exactly?

An name is valid when it passes the following tests:

  • It is not empty.
  • It consists only of the digits 0-9, the characters A-Z, and the characters: space, underscore, hyphen and period.
  • When used in a Name-Indexed document, it must be unique in the entire document.
Screenshot

If any of these rules are violated, the warning icon will be displayed besides the name to indicate it is invalid. In the example to the right, the presence of the extended ASCII character 'รถ' causes the name to be invalid.

When exporting a document, the editor will issue an error if the document contains any invalid strings. These must be fixed before exporting.

7. Importing DAT files

When importing a DAT file, the editor reads the contents of the specified DAT file and adds it to the open document, using the selected language.

There are however, several methods by which to add the strings to the open document:

Import methods for Name-Indexed documents

Screenshot
  1. Union
    For every string in the imported file it will check if a string with the same exists in the document. If not, it will add it. If so, it will either skip the string, or overwrite the existing string, depending on the "Overwrite" checkbox.
  2. Intersection
    This will delete all strings in the current version that does not have a similarly named string in the imported file.
  3. Difference
    This will delete all strings in the current version except those do not have a similarly named string in the imported file.

Import methods for Index-Indexed documents

Screenshot
  1. Overwrite
    This will overwrite as many strings as possible in the current document from the start based on matching names. When, during the overwrite, the name of the current string and the imported string do not match, it will resume overwriting at the first string in the document that matches the imported string's name again.
  2. Append
    This will add the strings in the imported file to the back of the strings in the document.

8. Exporting DAT files

Screenshot

Exporting a document to DAT files means that all <name, value> pairs will be written to the specified DAT file, ordered based on the document type.

When you select the "Export" option in the "File" menu, the editor first checks if the document contains no invalid names. If this is not the case, the "Export .DAT files" dialog will be presented. Here you can enter a base filename and a per-language postfix.

Use the checkboxes in front of the languages to select which languages will be exported.

In the example to the right, the base name is "MasterTextFile.dat". With the postfixes shown, this will mean that the current version's german strings will be written to "MasterTextFile_GERMAN.dat", the english strings to "MasterTextFile_ENGLISH.DAT", etc.

9. The console version

Screenshot

The console version of the application can be reached by starting the application from the command line, with arguments.

Unless you use a correct sequence of commands, the help text will be shown. This will explain how to use it and what the commands are.

The console version is intend to automate deployment of a VDF file into DAT files. It is not meant as a complete replacement of the GUI version, and the selection of available commands reflect this.

10. Tutorial

Fynbos has written a tutorial for the editor.

Changelog
v1.4:Added german language version.(2008/06/05)
v1.3:Fixed a bug that occured when cutting text (thanks, Phoenix Rising).(2007/07/05)
v1.2:Added scroll bars to the version and language dropdown boxes.(2007/03/21)
v1.1:Three bugfixes:
  • When exporting after saving, the editor wouldn't export string values.
  • When saving after starting a new file, it would overwrite the previously opened file.
  • In the export dialog, the names of the languages were cut off.
Thanks to Phoenix Rising for discovering the first one.
(2006/11/07)
v1.0:Initial release(2006/09/13)