Helping Max with DateDifference, we wanted a way to parse a date string using the user’s current locale. We naturally found the dateWithNaturalString:locale: method on NSDate. It sounds perfect. The documentation for the method includes this statement:
This method supports only a limited set of colloquial phrases, primarily in English. It may give unexpected results, and its use is strongly discouraged.
There’s an obvious next question here, and I wish the doc writer had thought enough about their reader to answer it: if this method’s use is strongly discouraged, what is the recommended way to solve my problem?
This isn’t meant to be a dig at Apple. There’s tons of reference documentation all over the place just like this. There are probably even tech writers that defend this style, in the name of modularity and brevity. Don’t believe it. This is unhelpful, exactly the opposite of what docs should be.
Extra bonus question: if you can help me understand how to parse dates according to the user’s current choices in the International system preferences panel, I would really appreciate it!