I spent a significant portion of the second half of last week struggling with an issue in a Ruby on Rails project I work on regularly. This post is a postmortem on the issue.
Sometime in the middle of last week I started seeing rspec failures that looked like this:
undefined method `=' for :used:Symbol
I modified the stack trace because it came from various different specs, and the exact details don’t matter right now. The important thing to know is that the failures appeared to be random (different number of failures every time), the stack trace always terminated in the same method in the ApplicationController, and the method in the ApplicationController rendered a partial that lives inside a gem included in the Gemfile. We’ll refer to this external gem as common_components from here on.
The main reason that I struggled with this issue for so long is that I didn’t know about the -b option for rpsec. If you run rspec with the -b option, it will show you detailed stack traces. By default it only shows you the part of the stack trace relevant to your current project. Once I tried this, the detailed stack trace gave me a much better idea of where the problem was. I’ll spare you the massive stack trace that was generated and just say that the error was coming from common_components/_error.html.haml. The line the error was coming from looked like this:
Looking even further along in the stack trace I could see that the error was coming from gems/i18n-extra_translations-0.0.5/lib/i18n/extra_translations/store.rb:17:in `add_key’. I didn’t understand why this code was throwing an error, so I dug into the source code. The error came from line 17 of store.rb, which looks like this:
This store class inherits from Hash and is used as a container of all translation keys used by the application. The gem has an extender which replaced the I18n.translate method and will call store.miss or store.use. These two methods call the protected method add_key and tell it to add the key to the store with either a :used or a :miss result. The use of keys.inject on line 16 is a crafty way of building a nested Hash structure based on the dot separated translation keys. For instance, if these were the only two translations used in the application:
Then the store would end up looking like this:
That code took a little bit to parse in my head, but once I figured out exactly how it was working, I still wasn’t quite sure why the error was happening. Clearly, line 16 sets h to a Hash, so why is it saying h is :used:Symbol on line 17? It didn’t make sense.
After a few minutes of head scratching, I realized that we had conflicting translation keys. It would make sense that h is set to :used in the case that add_keys has already been called with a less specific key then we’re currently adding.
Take the following translation files for example:
Now let’s step through, at a relatively high level, what happens in i18n-extra_translations when these keys are translated:
- I18n.translate(‘en.error’) is called.
- The store now looks like:
- I18n.translate(‘en.error.default_header’) is called.
- store.use is called for this key which in turn calls add_keys.
- On line 16 of store.rb, h is set to :used instead of an empty hash because it’s already been initialized in the previous I18n.translate call.
- On line 17, = is undefined for :used:Symbol because it’s expecting h to be a Hash, not a symbol.
The problem became extremely clear once I realized what was happening. If you have “conflicting” translations, and a less specific translation is used after a more specific translation, the i18n-extra_translations gem can’t handle it. This also explains why the failures were random… since rspec runs tests in a random order, which tests failed would depend on which order the translations were called.
I’ve logged an issue on the project in GitHub. For now, we can fix the issue by “namespacing” translations in the common_components gem under a root key. For example, en.common_components.error.default_message instead of en.error.default_message.
The i18n-extra_translations gem (source) has a bug – or unsupported use case – that doesn’t allow it to function correctly in the case that you have conflicting translation files loaded. For instance, if a gem you’ve included in your project has the key en.error.default_message=”Internal Server Error” and your application has the key en.error=”Error” the i18n-extra_translations gem will fail internally with the error undefined method `=’ for :used:Symbol.