FAQ

  1. How can I view a message's versions (history)?
  2. I made some changes in an IDE and when I returned those changes were gone.
  3. What is the difference between missing and intentionally missing?
  4. What is intentionally missing and when should I use it?
  5. What does incomplete mean?
  6. Should we wait until we're ready to do translations to use j18n?
  7. Does j18n provide CAT (computer-aided translation)?
  8. Can you explain how to use resource inheritance?
  9. Why would anyone not choose generate inherited as a build option?
  10. We have existing resources (java .properties files). How do we import them into j18n?
  11. Are there limits on the number of builds?
  12. Which type of build should we normally use (incremental or clean)?
  13. Are there limits on the number of imports?
  14. What resource formats are supported for importing?
  15. How do we integrate our j18n project into our own SCC/builds?
  16. What are the system requirements?
  17. Any tips, suggestions on how to get the most out of j18n?

If you don't see your question,

  1. How can I view a message's versions (history)?

    Click the leftmost cell for the message's row. This is the same for all three IDEs (Master, Foreign, ToDo). Here's a handy guide.

  2. I made some changes in an IDE and when I returned those changes were gone.

    All changes only become permanent when you save them by clicking on the save toolbar button—including deleted rows. Here's a handy guide.

  3. What is the difference between missing and intentionally missing?

    First, there is no difference in terms of what is output (by a build or preview source), viz. missing and intentionally missing messages do not appear
    What is different is in how they are counted as incomplete—intentionally missing messages do not count as incomplete, while missing messages do.

  4. What is intentionally missing and when should I use it?

    If you mark a message (row) in a foreign resource as intentionally missing, then that message will not appear in a build (taking advantage of Java's locale inheritance*).
    However, that message will not be counted as incomplete (that's the intentional part)
    This is actually not uncommon in practice:
    E.g. your master locale is English and you have a foreign locale of French and you need to localize a list of countries.
    Say you have defined a key, country.fr for the country France. The English (master) version of "France" is the same in French. In such a case, you could mark "country.fr" in the French resource as intentionally missing.
    Not only would it save your translators from needlessly copying the text, but if for some reason you were to change the master text to an abbreviation, e.g. "Fr", the French version would not be counted as incomplete (and therefore does not require any translation to keep it up-to-date).
    Another common example is when you provide some legal language (e.g. a license). In such a case, you may only want to provide a single version or a few select foreign versions.

  5. What does incomplete mean?

    It is useful for some to think of incomplete as todo (we went back and forth ourselves). Messages that are missing or out-of-date are incomplete, i.e. they still need to be finished.
    By keeping track of incompletes, you can answer the questions "Where are we?" or "What's left?"
    j18n keeps track of incomplete at several levels:
    a. Project
    b. Locale
    c. Foreign resource (which determines the above)
    Note: master locale and resources are never incomplete by definition

  6. Should we wait until we're ready to do translations to use j18n?

    It depends on how far along you are in development, your development cycle, et al.
    But there are several j18n features that are useful even if you are not ready to actually begin localization:
    a. Team-integration
    Product, QA, client-services, sales, management—whomever defines the master content for your project can just enter content; without any expenditure of precious engineering resources
    b. Resource Inheritance
    In addition to the benefits of reuse (standardization) and modularization, resource inheritance makes i18n easier (since you only need to deal with a single resource regardless of the context)
    c. Content versioning
    Master content is versioned, so you can view the history of a message's content, revert to a previous version, etc.

  7. Does j18n provide CAT (computer-aided translation)?

    No. Our experience is that CAT is a poor substitute for human translation, which can account for context and nuance in a way that no computer program sufficiently can.

  8. Can you explain how to use resource inheritance?

    Let's use a real-world example
    Since j18n was used to develop j18n:
    We have a resource user which contains all the content relevant to user views (add/edit, read, list, et al)
    So it contains keys like invalid.login.null
    invalid.password.toolong
    ...     All of our user views also need to display menus (in the header/footer). We have defined a menu resource for all menu content:
    menu.main.project
    menu.main.user
    ...     So we define user as extending menu. This gives us all the typical advantages of code-reuse (modularity, fewer translations, consistent translations, etc), but in addition it means that our i18n code only needs to deal with a single ResourceBundle:
    ResourceBundle rb = ResourceBundle.getBundle("user", locale);
    rb.getObject("menu.main.user"); //works!!
    ...     Note: We actually use an abstraction over ResourceBundle that is integrated into our templating code. It transparently loads the appropriate resource and user locale
    And in the case where a specific context needs different content, you can override the key, so within user you could: menu.main.project Some user-specific menu
     So with this one simple idea, you can simplify/improve your i18n, l10n, and your GUI templating
    The point is the same though. With resource inheritance, you can decouple the structure/organization of your resources from the actual jdk mechanism/API. All of the standard advantages of DRY (modularity, reuse) yet all the simplicity of working with a single resource. With each distinct rendering context (which in our case is a view or html file), we assign it a single resource yet have access to content in all the resources in its inheritance graph.

  9. Why would anyone not choose generate inherited as a build option?

    a. you don't use resource inheritance
    b. you implement resource inheritance in your own way, e.g. by writing your own subclass of ResourceBundle
    When j18n does a build with generate inherited, it flattens out the inheritance graph (depth-first traversal) and then includes each super resource into the output java .properties file (taking care to avoid duplicates). This produces java .properties files that are fast and simple to use, but the total size of your resource.jar will be larger.

  10. We have existing resources (java .properties files). How do we import them into j18n?

    By using the import feature. Details here

  11. Are there limits on the number of builds?

    No. j18n ensures that there is only one scheduled build for a project at a time

  12. Which type of build should we normally use (incremental or clean)?

    It depends. Incremental builds will generally be faster than clean builds.
    Note: j18n sometimes escalates a build from incremental to clean (e.g. when there has been a change to the project).
    For what it's worth, we almost always used incremental builds for j18n itself.
    A detailed explanation of the difference between build types

  13. Are there limits on the number of imports?

    No. We should caution however that imports are designed to be done at the start of working on a j18n project—and they are not designed to be a sort of backdoor reverse integration, i.e. where you attempt to integrate any changes you've made in a local working copy with a j18n project—that won't work. Details here

  14. What resource formats are supported for importing?

    Currently, we only support importing resources that are in standard java .properties files. Specifically, all imported resources are read using Properties.load(InputStream)

  15. How do we integrate our j18n project into our own SCC/builds?

    You can either schedule a build (and then download the jar) or use preview source and then copy the source into a java .properties file in your SCC working copy.

  16. What are the system requirements?

    A modern browser. An Internet connection.
    Javascript must be enabled and you must allow 1st-party session cookies (and it is strongly recommended that you allow 1st-party permanent cookies (so you won't have to login))
    3rd-party cookies may be disabled (we don't use any)

  17. Any tips, suggestions on how to get the most out of j18n?

    A lot of the suggestions below are just that, suggestions. Mostly they reflect our own experience of using j18n to develop j18n.
    — Make your resources relatively small (# of keys); you can always use resource inheritance to get the same effect of large resources.
    — At the same time, don't go overboard on the size of your inheritance graph; just as in traditional OO inheritance, a too deep inheritance graph can lead to confusion.
    — Define a simple unzip task (in Ant, Maven, your build tool of choice) that extracts the java .properties file from the build jars. By doing that, you can use either build type (clean or incremental) or preview source as you choose in order to integrate your j18n project with your SCC working copy, e.g. we would always save the build jar as the same name (whether a clean or incremental) and just run an unzip Ant task to extract the java .properties files; and then as part of our build (or package) we would just zip the java .properties file into a resource.jar
    — Use the Notes column in the IDE liberally—to provide instructions to translators, provide context, identify where the text shows up, etc.
    — Learn to use the keyboard as much as possible in the IDE views when entering content; you can scroll forward/backwards, open/close editors, etc.
    — Select the Remember Me option so you can avoid having to repeatedly login and session timeouts.
    — Use Firefox, Chrome, etc., i.e. avoid IE, if at all possible. j18n works in IE 7/8, but especially if you have large resources and/or inheritance graphs, IE is markedly slower in dealing with large grid-like content.
    — Only add a foreign locale to your project when you are ready to localize/translate (or import) for it—you'll experience a slight performance improvement, have slightly smaller jars, etc.