Quantcast

Massive update to the localization notes

Kevin Lyles [08-28-10 - 20:59]
Massive update to the localization notes
Filename
localization notes
diff --git a/localization notes b/localization notes
index 12957ea..c4b5b1b 100644
--- a/localization notes
+++ b/localization notes
@@ -1,15 +1,20 @@
-translation instructions:
+files to translate (inside Locales/<your locale>):
 	minimum:
 		stats.lua
-		base.lua
 		gems.lua
-		patterns-base.lua
+		patterns-generic.lua
+		patterns-sockets.lua
+		patterns-socket-bonuses.lua
 		patterns.lua
-			NOTE: you can safely skip those patterns whose section table only includes cooldownUseEffects and/or stackingEquipEffects (or any other of the recommended and later files you're skipping)
+			NOTE: you can safely skip those patterns whose category table only includes cooldownUseEffects and/or stackingEquipEffects (or any other of the recommended and later files you're skipping)
+			NOTE: if you do not translate some files, the matching variables need to be commented out or removed from ww_EffectHandlers (near line 5)
 		classes-specs.lua
 		slots.lua
 		dropdown-options.lua
-		<locale name>.xml (which will include all the other localization files)
+		base.lua
+		<locale name>.xml
+			includes all the other localization files as scripts
+			should not need much updating (none if you translate everything)
 	recommended (in recommended order of completion):
 		patterns-equip-stats.lua
 		patterns-elixirs.lua
@@ -17,23 +22,123 @@ translation instructions:
 		patterns-food.lua
 		patterns-enchants.lua
 		patterns-fishing.lua
-	"extra" features (the UI will change if these are not done, but everything else should still work):
+	"extra" features (the UI will change but still work minus these features if these are not done):
 		patterns-cooldown-use-effects.lua
 		patterns-stacking-equip-effects.lua
+			NOTE: triggerGroups is translated backwards.  That is, the left hand side should be translated, with the right hand side remaining in English.

 Notes:
+	You will need lua installed to properly test the translation
+		WeightsWatcher has an offline mode that can test every item in the game in under a minute on a fast machine, which can be much more efficient than testing everything in-game.
 	You must keep the names of all non-local variables/functions the same
 	All files should be saved in UTF-8 format
 	Most quoted strings that are not part of ww_localization ('L' in most files) are actually lua patterns.  These are similar to regular expressions, but vary in several important ways.  See http://www.lua.org/manual/5.1/manual.html#5.4.1 for more information about patterns.
 		A few specific notes:
 			to include a literal dash ('-') in a pattern, you must use "%-" or the pattern will not match
-				parentheses and periods are the same way
+				parentheses, periods, and % are the same way
+			%a and similar will probably NOT change with your locale based on my testing.  This is due to Blizzard using their own version of lua.
 	If you encounter a lua error, PLEASE let me know!  I have only one other language to test with, and I may have missed something.
+	For in-game testing, tekErr and tekKompare are highly recommended
+		tekErr will log nil errors for much easier tracking down and fixing
+		tekKompare allows you to use modifier keys on item links pasted from wowhead or similar sites
+
+Recommended development process:
+	1.	copy the Locales/enUS folder to Locales/<your locale> and change the locale on line 1 of each lua file in the new folder
+	2.	translate ww_localizedSocketColors (gems.lua), ww_localizedSlotNames (slots.lua), and ww_localizedStats (stats.lua)
+			NOTE: not all stats actually appear in-game as worded here.
+	3.	get a full list of item data using the ItemScanner addon
+			See notes about ItemScanner below
+			Once you have the final combined item data, copy or move it into the WeightsWatcher directory as item-info-<your locale>.lua
+				If there are items that are in either item-info-enUS.lua or the file you just created, but not both, you should remove the items so that your item lists are the same
+					NOTE: if the item is missing from item-info-enUS.lua, you can e-mail me with the item number and I will try to scan that item again
+					If you have more than 50 or so of these items that are missing from your file, it probably means that ItemScanner did not work properly and you should try again after removing ItemScanner's SavedVariables files
+					If you have several thousand of these items that are missing from your file, you either did not do a full scan or forgot to get the data before doing the next section, and should re-read the ItemScanner notes below
+	4.	decide whether you'd rather have your output in english or the language you're translating to
+			NOTE: only item and enchant data is translated automatically.
+			If you want to work in English:
+				run an offline scan:
+					lua -i standalone-data-scanner.lua
+				edit standalone-data-scanner.lua:
+					comment line 153 and uncomment line 154
+					comment line 159 and uncomment line 160
+			If you want to work in the language you're translating to:
+				edit standalone-data-scanner.lua:
+					comment line 182
+					change line 184 to the locale you're translating to
+				run an offline scan:
+					lua -i standalone-data-scanner.lua (make sure you save everything first)
+				edit standalone-data-scanner.lua again:
+					uncomment line 182
+	5.	edit wrapper-functions.lua:
+			change line 45 to the locale you're translating to
+	6.	translate the rest of the minimum files
+			you can save most of base.lua for later as it only affects the UI
+				you should translate the talent names and item types though
+					lines 82, 83, and 114-118
+	7.	run an offline scan:
+			delete the contents of output-<your locale> and create that folder if it doesn't exist
+			lua -i standalone-data-scanner.lua
+	8.	compare your results to the output-enUS folder
+			NOTE: only the item_data-*.lua and enchant_data.lua files are translated (and therefore comparable)
+			NOTE: until you finish translating everything, there will be differences
+				try to make sure the differences in the file(s) you're working on have been removed before moving on
+	9.	translate a recommended file and go to step 7.  repeat until the results look right
+	10.	translate an "extra" file and go to step 7, etc.
+
+Notes about ItemScanner:
+	I recommend running ItemScanner as a druid to get feral attack power to show up
+	You will need to run at least 3 scans to get most of the in-game items
+	Each scan has to be done in 3 parts due to a size limit of the SavedVariables files
+	ItemScanner will print out a status message every 2 minutes.  If you don't see one after waiting 2 minutes, it likely finished and you missed the message.
+	WARNING: ItemScanner used to disconnect me on a fairly regular basis.  I am fairly sure I have fixed the problem, but it could still be lurking somewhere.
+		The fix for this is the main reason the time delays are the way there are.  I don't recommend shortening them, especially the 5 seconds waiting for an invalid item.
+	The first couple of runs will take several hours each, later runs will be faster but will only update items you have already seen with ItemScanner
+		You can reset the list of what's been seen by deleting itemScanner's SavedVariables file
+			This will make the next 2 scans take several hours again, but may get items you had missed before
+	I highly recommend using some sort of source control on the scanned directory so you can easily combine results from multiple scans
+	Normal ItemScanner flow:
+		Start a scan with /is items reset
+			If the scan is interrupted, you can resume it with /is items
+			Once the scan finishes, reload ui or logout
+				Run lua get-live-data.lua
+		Start the next segment with /is items next-chunk
+			Once the segment finishes, reload ui or logout and re-run get-live-data.lua
+		Start the last segment with /is items next-chunk and /is enchants
+			Wait for the enchant scan to finish before reloading ui or logging out
+			You can run both command at once; the enchant scan will wait for the item scan to finish first
+			Again, reload ui or logout and re-run get-live-data.lua
+		Finally, run lua splice-item-info.lua to combine the results into a single file
+			The final file size should be at least 30 megabytes, and may be much larger for some locales
+
+Notes about the general structure of WeightsWatcher:
+	ww_MultipleStatLines should contain one rule for each way that multiple stats are worded
+	ww_SingleStatLines should contain one rule for each stat
+		use the other patterns files to change text to match the most common usage for each stat
+	The last part of each rule in ww_MultipleStatLines and ww_SingleStatLines is a listing of the categories the rule will be used for.  There is a category for each patterns-*.lua file (see the next note).
+	The patterns-*.lua files all finish with a variable that will eventually be passed to WeightsWatcher.handleEffects()
+		The contents of that variable, in order:
+			MatchLines: used to check if a particular line should be parsed with this handler
+			IgnoreLines: used to remove lines from consideration and ignore them
+			UnweightedLines: used ot indicate that a line cannot be parsed (but should not be totally ignored)
+			PreprocessLines: a table of tables, with each subtable containing two string that will be passed as the second and third arguments to string.gsub (with the current line as the first).  Used to re-word a line for easier parsing or to change to a more-common wording.
+			Affixes: a list of string that should be removed from the current line, in order.  Used to strip away extra information.
+			Handler: the function that will be called on what is left of the current line.  Usually WeightsWatcher.parseStats, but some files have their own function to handle this differently.
+			CategoryName: a string indicating which patterns in patterns.lua should be used to parse the current line.  Should not be changed.
+		All of these except the last 2 can be empty ({}).  However, if the first one is empty, the file is effectively doing nothing.
+	In general, stats and other things parsed from items are not translated into english until the scores for the item are calculated
+	All things that are saved to SavedVariables should be in English
+		For example, stat names in the weights
+	Most things put into tooltips are translated as they're displayed
+		The main exception is stat names
+		Some debug info is not translated at all
+	Ranged weapons should have their damage, dps, and weapon speed parsed as if they were melee weapons
+		WeightsWatcher.getItemStats will convert these to ranged stats on ranged weapons
+
+Finally, a translation for mastery rating would be most appreciated.  You can put it in stats.lua or just mention it in your e-mail when you send back your translation.  I do not know what other changes Cataclysm will bring, but it would be nice to have that one out of the way ahead of time.
+
+Please contact me if you have any questions or problems.
+
+Thank you for your help!

-add bit about tekerr and tekkompare
-add bit about not splitting your regexes too soon
-add bit about triggerGroups being special
-note about localization.lua and enabling errors
-add notes about itemscanner to localization info
-	also notes about what is and is not localized in which part of the addon
-note about making unspecified stats melee (WeightsWatcher.lua converts them to ranged as needed)
+IQgryn
+WeightsWatcher@gmail.com