[item-name] vs [entity-name] localization keys

[metalbass_92]

I've noticed a mod I'm using (Hiladdar's Robots) has something strange happening on localization texts, so I went in and tried to "fix it", as a good first approach to see how a mods works.

While I was doing that I thought that it had a lot of duplicated localization keys, like:

Code: Select all

[item-name]
hsmd-construction-robotics-mk2=Construction robotics
[item-description]
hsmd-construction-robotics-mk2=Construction robotics, with better battries and a bit more speed.
[technology-name]
hsmd-construction-robotics-mk2=Construction robot MK2
[technology-description]
hsmd-construction-robotics-mk2=Construction robots with improved battary.
[entity-name]
hsmd-construction-robotics-mk2=Construction robotics MK2

Are item-name.hsmd-construction-robotics-mk2 and item-description.hsmd-construction-robotics-mk2 not duplicates, but 2 different localization keys?

Since I haven't been able to find any reference to "item-name" in the code of the mod, I replaced the text of the keys with something I could recognize (i.e. "tag" + "key") but I haven't been able to see any use of the texts under [item-name] tag.
Hiladdar's Robots is a pretty simple mod that just defines some entities and techs with little scripting other than calling data:extend().
All this makes me think the game looks up for this instead of the mod.

So, am I right to say that the game looks up for entity-name.hsmd-construction-robotics-mk2 since the entity name is set like this?

Code: Select all

local cmk2 = table.deepcopy(data.raw['construction-robot']['construction-robot']);
cmk2.name = "hsmd-construction-robotics-mk2";

For which cases is [item-name] used?

[DaveMcW]

For which cases is [item-name] used?

prototypes/item/hsmd-construction-robotics-mk2.lua

[Pi-C]

While I was doing that I thought that it had a lot of duplicated localization keys, like:

Code: Select all

[item-name]
hsmd-construction-robotics-mk2=Construction robotics
[item-description]
hsmd-construction-robotics-mk2=Construction robotics, with better battries and a bit more speed.

Are item-name.hsmd-construction-robotics-mk2 and item-description.hsmd-construction-robotics-mk2 not duplicates, but 2 different localization keys?

Consider this image:

item_locale.png (103.68 KiB) Viewed 2030 times

On the left, the Active provider chest has both [item-name] ("Active provider chest") and [item-description] ("Sends its content to the logistic network.") set. The stone furnace on the right only has [item-name] ("Stone furnace", anything below the name is automatically filled in by the game). [item-description] provides additional information but is optional, while [item-name] should always be set.

Since I haven't been able to find any reference to "item-name" in the code of the mod, I replaced the text of the keys with something I could recognize (i.e. "tag" + "key") but I haven't been able to see any use of the texts under [item-name] tag.

Think of it this way: There are two environments. One is global -- the complete game. The game has to know the names of all items, recipes, entities, and settings, so categories like [item-name], [recipe-description] etc. are hard-coded, and all keys in these categories are shared by all mods. Say, to mods create their own item "big-miner". They would compete over whose localization is used throughout the game (the mod that is loaded last will "win" and overwrite the other mod's definition). That's why, names of items, recipes etc. should be prefixed with a marker (e.g. "my_mod_big-miner") that makes it less likely that it would be overwritten by another mod.
The other environment is local -- it's reserved for each mod. So you could define a category like "[my_mod_messages]". It wouldn't matter if another mod defined keys of the same name. Say, mod A has a key "defeat=You lost", while mod B has the same key with a different meaning (e.g. "defeat=You defeated a behemoth worm!"), this wouldn't matter because one would be referred to as "mod_A_messages.defeat" and the other as "mod_B_status.defeat" (i.e. the keys would be in different categories).

It's also possible to "fix" the translation of other mods. For example, if the author of mod A knows that mod B is missing a localization key, it could include

Code: Select all

[category_from_B]
missing_key=Translation

to add it. (It would only fix the problem for players who use both mod A and mod B, though.) Loading order wouldn't matter in this case because something new is added. If the author of A would want to change something from B (for example, terrible spelling in an abandoned mod), this could be done the same way -- only then, A would have to add a dependency on B so B gets loaded first.

So, am I right to say that the game looks up for entity-name.hsmd-construction-robotics-mk2 since the entity name is set like this?

Code: Select all

local cmk2 = table.deepcopy(data.raw['construction-robot']['construction-robot']);
cmk2.name = "hsmd-construction-robotics-mk2";

For which cases is [item-name] used?

Items are the thing in inventories (character inventory, fuel/weapon/trunk inventories of cars etc., contents of chests, input/output of assemblers etc.), moving on belts, or dropped on the ground. They become an entity once you "build" them -- e.g. a furnace will be an item when you put pick it up; when you place it on the ground and can melt ore in it, it has become an entity; if you mine it, it will become an item again.

[metalbass_92]

Hi!

With this localization file:

Code: Select all

[item-name]
hsmd-construction-robotics-mk2=ITEM NAME!
[entity-name]
hsmd-construction-robotics-mk2=ENTITY NAME!

I see this if I create the item and place it on a wooden chest:

entityname.png (69.33 KiB) Viewed 2013 times

And see this on the ground:

entityname on ground.png (26.92 KiB) Viewed 2013 times

And on recipes:

entityname on recipe.png (107.48 KiB) Viewed 2013 times

I even tried moving all the item names to the bottom of the file to see if the order of the localization texts was important or not. It is not, as expected.

@DaveMcW, this is the content of the file you mention:

Code: Select all

data:extend({

  {
    type = "item",
    name = "hsmd-construction-robotics-mk2",
    icon = "__Hiladdar_Robots__/graphics/icons/hsmd-construction-robot-mk2.png",
    icon_size = 64,
    icon_mipmaps = 4,
    subgroup = "logistic-network",
    order = "a[robot]-b[construction-robot]",
    place_result = "hsmd-construction-robotics-mk2",
    stack_size = 50
  }

})

There's nothing that indicates that the item name is used here (instead of the entity name). In fact, my tests tell me the opposite.

My feeling is that I'm missing where the item-name is being used, as the base game and other mods all use it, but I can't find any usage of it. :/

[Hiladdar]

My understanding is that they are two separate keys, one provides a name and one provides a description. I did some testing and found out that I do need to have an item name, item description, entity name, and entity description, in the locale file. Although it may appear redundant, each one is accessed, by different parts of the UI. By including all four of those descriptors, I avoid my mod displaying something like "entity.hsmd-construction-robotics-mk2" in the UI during a game.

I try to preface all the variable names in my mods with "hsmd_". The primary reason is for my mods to play nice with other developer's mods. I can see situations where a player will want to use 2 different robot mods, for example, roboports from my mod, and robots from another mod or visa versa. Using this naming convention prevents name collision errors.

It may be possible to make a mod which includes different language localization. In this case the json file will control the order in which mods are loaded via optional dependencies. I've seen several mods that provide nothing more then different language pack other mods. Downloading one of those mods and taking a look at how a languages are added might make sense.

From a design perspective, I try to keep each mod small and simple, it makes the mod much more maintainable, and easier for players to integrate with other mods. Also, Factorio has not yet been released as version 1.0, and like other mod developers my mods are sometimes broken upon a new experimental release. It is much easier and quicker to fix small mod rather then a large mod. One of the more frustrating things for a player, is to be suck on an older release of Factorio, due to the mod mod crashing upon loading the current experimental version. The final reason, I am attempting to keep things simple is that although I have programmed in the past, it was probably long before most players were even born, and everything that I have done, including graphics, I had to learn on my own, while learning the game. Let's just say, I still have a few punch cards and 8" floppy disks, that I kept around as mementos.

Hiladdar

[boskid]

[ItemPrototype logic] If ItemPrototype has no localised_name, then it will take default one same as defining it to be {"entity-name.%s"} with %s being name of the item. [Item Tooltip logic] If ItemPrototype resolved localised name is empty, place_result localised_name will be taken (fallback). 81736. At least this is how i remember it should work. (edit1: added scopes of logic)

[metalbass_92]

I'm just trying to piece everything together; it's hard for me to leave a subject without fully understanding it, so I usually dive into small irrelevant details.

Thank you @boskid for the answer! This means that, since the item-names are not being used manually, only the entity-names are used and there's no need to keep them all.

While I was trying to make sense of this I was looking at similar cases on the base game localization, and found item-name.artillery-turret, and entity-name:artillery-turret, which I now think they may be duplicates. Or the game code could be accessing both, can't say.

Thank you all!

[boskid]

Little more thorough description of how ItemPrototype localised_name should work:
1/ if `localised_name` is provided in ItemPrototype and it is not empty {}, use provided value
2/ else if there is place result and it has localised name that is not empty {}, use localised name of place result
3/ else if there is place result with empty localised name, use {"entity-name.<name>"}
4/ else if there is equipment place result and it has localised name that is not empty {}, use localised name of equipment place result
5/ else if there is equipment place result with empty localised name, use {"equipment-name.<name>"}
6/ else use defaut {"item-name.<name>"}

i hope i did not made any huge mistakes this time

[metalbass_92]

Thank you for the amount of detail boskid!

I wonder if this should get into the wiki or docs; let me know if I can help with that.